AGNTDocs

Context

Contacts

The people a user works with, across email, phone and chat, with relationships and external ids.

GET/contacts

List contacts

Returns the user's contacts, filtered by `status`, `scope`, `source` or `tags`, or searched by name and email. With an account key and no `X-User-Email`, pass `userId`.

Query parameters

pageinteger
perPageinteger
userIdstring
statusstring
searchstring
qstring
scopestring
sourceTypestring
tagsstring

Responses

200Contacts
ok reqenumtrue
contacts reqobject[]
id reqstring
user reqstring
name reqstring | null
preferredNamestring | null
email reqstring
emailsobject[]
address reqstring
typeenumworkpersonalother
primaryboolean
sourcestring
phonesobject[]
number reqstring
typeenumworkmobilehomeother
primaryboolean
sourcestring
iMessageCapableboolean | null
company reqobject | null
id reqstring
name reqstring
slug reqstring
domain reqstring | null
title reqstring | null
timezone reqstring | null
tzOffsetstring | null
photoUrlstring | null
website reqstring | null
bookingLink reqstring | null
socialobject
linkedInstring
xstring
otherstring
addressobject
line1string
line2string
citystring
statestring
zipstring
countrystring
enrichedAtstring | null
sourceobject | null
typeenummanualteammateteammate_archivedimportedemailimportcrmatshrisvoiceonboardingcalendarothernull
userIdstring | null
lastContactedAtstring | null
externalIdsobject[]
integration reqstring
externalId reqstring
syncedAtstring | null
propertiesobject
priorityinteger
inheritCompanyPriorityboolean
tagsstring[]
introducedBystring | null
scopeenumuserteam
teamstring | null
status reqstring
consumerobject | nullWhen the contact is also a user of your app: that user. Otherwise null.
id reqstring
name reqstring | null
email reqstring | null
createdAt reqstring
updatedAt reqstring
assistantobject | null
namestring | null
emailstring | null
userIdentifierstring | null
sourceenummanualnull
internalboolean
isMemberboolean
pageinteger
perPageinteger
totalinteger
400No user: send X-User-Email, or pass userId with an account key
statusinteger
error_codestring
errorstring

Request

curl 'https://api.agnt.ai/contacts' \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "contacts": [
    {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "user": "user",
      "name": "Ava",
      "email": "[email protected]",
      "company": {
        "id": "6660c4a1f2e3b7d8a9c01234",
        "name": "Ava",
        "slug": "slug",
        "domain": "harborview.co"
      },
      "title": "Send Brightline the contract renewal"
    }
  ]
}
POST/contacts

Create a contact

Creates a contact for the user. When the email address belongs to a user of your app, `consumer` links the contact to that user.

Request body

email reqstring
namestring
preferredNamestring
phonesobject[]
number reqstring
typeenummobileworkhomeother
primaryboolean
emailsobject[]
address reqstring
typeenumpersonalworkother
primaryboolean
companystring
titlestring
timezonestring
consumerEmailstringAddress used to link the contact to a user of your app; defaults to email
sourcestring | object | null
externalIdsobject[]
integration reqstring
externalId reqstring
propertiesobject
scopeenumuserteam
teamstring
tagsstring[]
priorityinteger
inheritCompanyPriorityboolean

Responses

201Created
ok reqenumtrue
contact reqobject
id reqstring
user reqstring
name reqstring | null
preferredNamestring | null
email reqstring
emailsobject[]
address reqstring
typeenumworkpersonalother
primaryboolean
sourcestring
phonesobject[]
number reqstring
typeenumworkmobilehomeother
primaryboolean
sourcestring
iMessageCapableboolean | null
company reqobject | null
id reqstring
name reqstring
slug reqstring
domain reqstring | null
title reqstring | null
timezone reqstring | null
tzOffsetstring | null
photoUrlstring | null
website reqstring | null
bookingLink reqstring | null
socialobject
linkedInstring
xstring
otherstring
addressobject
line1string
line2string
citystring
statestring
zipstring
countrystring
enrichedAtstring | null
sourceobject | null
typeenummanualteammateteammate_archivedimportedemailimportcrmatshrisvoiceonboardingcalendarothernull
userIdstring | null
lastContactedAtstring | null
externalIdsobject[]
integration reqstring
externalId reqstring
syncedAtstring | null
propertiesobject
priorityinteger
inheritCompanyPriorityboolean
tagsstring[]
introducedBystring | null
scopeenumuserteam
teamstring | null
status reqstring
consumerobject | nullWhen the contact is also a user of your app: that user. Otherwise null.
id reqstring
name reqstring | null
email reqstring | null
createdAt reqstring
updatedAt reqstring
assistantobject | null
namestring | null
emailstring | null
userIdentifierstring | null
sourceenummanualnull
internalboolean
isMemberboolean
400email is missing, or a contact already has one of these addresses
401No user on the call: send X-User-Email with an account key, or use a user-scoped key
statusinteger
error_codestring
errorstring

Request

curl 'https://api.agnt.ai/contacts' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]"
}'

Response

{
  "ok": true,
  "contact": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "user": "user",
    "name": "Ava",
    "email": "[email protected]",
    "company": {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "name": "Ava",
      "slug": "slug",
      "domain": "harborview.co"
    },
    "title": "Send Brightline the contract renewal"
  }
}
GET/contacts/{contactId}

Retrieve a contact

Retrieves one of the user's contacts with its relationships.

Path parameters

contactId reqstring

Responses

200Contact
ok reqenumtrue
contact reqobject
idstring
userstring
namestring | null
preferredNamestring | null
emailstring
emailsobject[]
address reqstring
typeenumworkpersonalother
primaryboolean
sourcestring
phonesobject[]
number reqstring
typeenumworkmobilehomeother
primaryboolean
sourcestring
iMessageCapableboolean | null
companyobject | null
id reqstring
name reqstring
slug reqstring
domain reqstring | null
titlestring | null
timezonestring | null
tzOffsetstring | null
photoUrlstring | null
websitestring | null
bookingLinkstring | null
socialobject
linkedInstring
xstring
otherstring
addressobject
line1string
line2string
citystring
statestring
zipstring
countrystring
enrichedAtstring | null
sourceobject | null
typeenummanualteammateteammate_archivedimportedemailimportcrmatshrisvoiceonboardingcalendarothernull
userIdstring | null
lastContactedAtstring | null
externalIdsobject[]
integration reqstring
externalId reqstring
syncedAtstring | null
propertiesobject
priorityinteger
inheritCompanyPriorityboolean
tagsstring[]
introducedBystring | null
scopeenumuserteam
teamstring | null
statusstring
consumerobject | nullWhen the contact is also a user of your app: that user. Otherwise null.
id reqstring
name reqstring | null
email reqstring | null
createdAtstring
updatedAtstring
assistantobject | null
namestring | null
emailstring | null
userIdentifierstring | null
sourceenummanualnull
internalboolean
isMemberboolean
401No user on the call: send X-User-Email with an account key, or use a user-scoped key
statusinteger
error_codestring
errorstring

Request

curl 'https://api.agnt.ai/contacts/<contactId>' \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "contact": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "user": "user",
    "name": "Ava",
    "email": "[email protected]",
    "company": {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "name": "Ava",
      "slug": "slug",
      "domain": "harborview.co"
    },
    "title": "Send Brightline the contract renewal",
    "outgoingRelationships": [],
    "incomingRelationships": []
  }
}
PUT/contacts/{contactId}

Update a contact

Updates a contact. Only the fields you send change.

Path parameters

contactId reqstring

Request body

namestring
preferredNamestring | null
phonesobject[]
number reqstring
typeenummobileworkhomeother
primaryboolean
companystring | null
titlestring | null
timezonestring
statusstring
websitestring | null
bookingLinkstring | null
introducedBystring | null
socialobject
linkedInstring
xstring
otherstring
addressobject
line1string
line2string
citystring
statestring
zipstring
countrystring
emailsobject[]
address reqstring
typeenumpersonalworkother
primaryboolean
lastContactedAtstring | null
enrichedAtstring | null
propertiesobject
scopeenumuserteam
teamstring | null
tagsstring[]
priorityinteger
inheritCompanyPriorityboolean

Responses

200Updated
ok reqenumtrue
contact reqobject
id reqstring
user reqstring
name reqstring | null
preferredNamestring | null
email reqstring
emailsobject[]
address reqstring
typeenumworkpersonalother
primaryboolean
sourcestring
phonesobject[]
number reqstring
typeenumworkmobilehomeother
primaryboolean
sourcestring
iMessageCapableboolean | null
company reqobject | null
id reqstring
name reqstring
slug reqstring
domain reqstring | null
title reqstring | null
timezone reqstring | null
tzOffsetstring | null
photoUrlstring | null
website reqstring | null
bookingLink reqstring | null
socialobject
linkedInstring
xstring
otherstring
addressobject
line1string
line2string
citystring
statestring
zipstring
countrystring
enrichedAtstring | null
sourceobject | null
typeenummanualteammateteammate_archivedimportedemailimportcrmatshrisvoiceonboardingcalendarothernull
userIdstring | null
lastContactedAtstring | null
externalIdsobject[]
integration reqstring
externalId reqstring
syncedAtstring | null
propertiesobject
priorityinteger
inheritCompanyPriorityboolean
tagsstring[]
introducedBystring | null
scopeenumuserteam
teamstring | null
status reqstring
consumerobject | nullWhen the contact is also a user of your app: that user. Otherwise null.
id reqstring
name reqstring | null
email reqstring | null
createdAt reqstring
updatedAt reqstring
assistantobject | null
namestring | null
emailstring | null
userIdentifierstring | null
sourceenummanualnull
internalboolean
isMemberboolean
401No user on the call: send X-User-Email with an account key, or use a user-scoped key
statusinteger
error_codestring
errorstring

Request

curl 'https://api.agnt.ai/contacts/<contactId>' \
  -X PUT \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ava",
  "preferredName": "Ava",
  "phones": [
    {
      "number": "+14155550142"
    }
  ],
  "company": "company"
}'

Response

{
  "ok": true,
  "contact": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "user": "user",
    "name": "Ava",
    "email": "[email protected]",
    "company": {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "name": "Ava",
      "slug": "slug",
      "domain": "harborview.co"
    },
    "title": "Send Brightline the contract renewal"
  }
}
DELETE/contacts/{contactId}

Delete a contact

Deletes a contact.

Path parameters

contactId reqstring

Responses

200Deleted
ok reqenumtrue
contact reqobject
id reqstring
deletedboolean
messagestring
401No user on the call: send X-User-Email with an account key, or use a user-scoped key
statusinteger
error_codestring
errorstring

Request

curl 'https://api.agnt.ai/contacts/<contactId>' \
  -X DELETE \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "contact": {
    "id": "6660c4a1f2e3b7d8a9c01234"
  }
}
POST/contacts/bulk-import

Import contacts

Creates or updates up to 1,000 contacts in one call, matched to existing contacts by email. Rows with no email, or with an address already in the batch, are skipped and listed in `errors`.

Request body

contacts reqobject[]
email reqstring
namestring
preferredNamestring
phonestring
phonesobject[]
number reqstring
typeenummobileworkhomeother
primaryboolean
companystring
titlestring
timezonestring
emailsobject[]
address reqstring
typeenumpersonalworkother
primaryboolean
propertiesobject
tagsstring[]

Responses

200Import result
ok reqenumtrue
bulkImport reqobject
success reqboolean
total reqnumber
created reqnumber
updated reqnumber
skipped reqnumber
errors reqobject[]
indexnumber
emailstring
error reqstring
401No user on the call: send X-User-Email with an account key, or use a user-scoped key
statusinteger
error_codestring
errorstring

Request

curl 'https://api.agnt.ai/contacts/bulk-import' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "contacts": [
    {
      "email": "[email protected]"
    }
  ]
}'

Response

{
  "ok": true,
  "bulkImport": {
    "success": true,
    "total": 42,
    "created": 1,
    "updated": 1,
    "skipped": 1,
    "errors": [
      {
        "error": "error"
      }
    ]
  }
}
POST/contacts/{contactId}/merge

Merge contacts

Merges `mergeContactId` into this contact. Fields are combined, tasks and relationships move to this contact, and the other contact is deleted. `preferredEmail` sets the primary address.

Path parameters

contactId reqstring

Request body

mergeContactId reqstring
preferredEmailstring

Responses

200Merged
ok reqenumtrue
contact reqobject
idstring
userstring
namestring | null
preferredNamestring | null
emailstring
emailsobject[]
address reqstring
typeenumworkpersonalother
primaryboolean
sourcestring
phonesobject[]
number reqstring
typeenumworkmobilehomeother
primaryboolean
sourcestring
iMessageCapableboolean | null
companyobject | null
id reqstring
name reqstring
slug reqstring
domain reqstring | null
titlestring | null
timezonestring | null
tzOffsetstring | null
photoUrlstring | null
websitestring | null
bookingLinkstring | null
socialobject
linkedInstring
xstring
otherstring
addressobject
line1string
line2string
citystring
statestring
zipstring
countrystring
enrichedAtstring | null
sourceobject | null
typeenummanualteammateteammate_archivedimportedemailimportcrmatshrisvoiceonboardingcalendarothernull
userIdstring | null
lastContactedAtstring | null
externalIdsobject[]
integration reqstring
externalId reqstring
syncedAtstring | null
propertiesobject
priorityinteger
inheritCompanyPriorityboolean
tagsstring[]
introducedBystring | null
scopeenumuserteam
teamstring | null
statusstring
consumerobject | nullWhen the contact is also a user of your app: that user. Otherwise null.
id reqstring
name reqstring | null
email reqstring | null
createdAtstring
updatedAtstring
assistantobject | null
namestring | null
emailstring | null
userIdentifierstring | null
sourceenummanualnull
internalboolean
isMemberboolean
401No user on the call: send X-User-Email with an account key, or use a user-scoped key
statusinteger
error_codestring
errorstring

Request

curl 'https://api.agnt.ai/contacts/<contactId>/merge' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "mergeContactId": "6660c4a1f2e3b7d8a9c01234"
}'

Response

{
  "ok": true,
  "contact": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "user": "user",
    "name": "Ava",
    "email": "[email protected]",
    "company": {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "name": "Ava",
      "slug": "slug",
      "domain": "harborview.co"
    },
    "title": "Send Brightline the contract renewal",
    "merged": true,
    "mergedContactId": "6660c4a1f2e3b7d8a9c01234"
  }
}