AGNTDocs

Users and assistants

Identifiers

The phone numbers and email addresses that belong to a user, so inbound messages and calls reach the right person.

GET/identifiers

List identifiers

Returns identifiers in your account, filtered by `type` or `userId`. Called as a user, returns only that user's identifiers.

Query parameters

typestring
userIdstring

Responses

200Identifiers list
ok reqenumtrue
identifiers reqobject[]
id reqstring
account reqstring
user reqobject | null
id reqstring
name reqstring | null
status reqenumactiveinactivesuspended
type reqenumemailphoneexternal_idemployee_idgooglemicrosoftapplecustom
value reqstring
verified reqboolean
primary reqboolean
labelstring | null
platformsobject
metadataobject
iMessageCapableboolean | null
whatsAppCapableboolean | null
preferredTextPlatformenumimessagesmswhatsappnull
messagingWindowobject
whatsappany
imessageany
createdAt reqstring
updatedAt reqstring
pageinteger
perPageinteger
totalinteger

Request

curl 'https://api.agnt.ai/identifiers' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "identifiers": [
    {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "account": "account",
      "user": {
        "id": "6660c4a1f2e3b7d8a9c01234",
        "name": "Ava",
        "status": "active"
      },
      "type": "email",
      "value": "value",
      "verified": true
    }
  ]
}
POST/identifiers

Create an identifier

Adds an email address, phone number or other handle to a user, so messages from it reach that user. With an account key, pass `userId`. Phone numbers are stored in E.164; a number without a leading `+` uses the user's country. A value held by any user in your account returns `400`.

Request body

type reqenumemailphoneexternal_idemployee_idgooglemicrosoftapplecustom
value reqstring
userIdstring
verifiedboolean
labelstring | null
platformsobject
userDataobject
namestring
firstNamestring
lastNamestring
avatarstring
timezonestring
localestring

Responses

201Created
ok reqenumtrue
identifier reqobject
id reqstring
account reqstring
user reqobject
idstring
accountstring
emailstring
externalIdstring
assistantstring | null
namestring | null
firstNamestring
lastNamestring
avatarUrlstring | null
timezonestring
localestring
countrystring | null
citystring
organizationstring | null
organizationRoleenumadminmemberguest
teamany
teamRoleenummemberadminownernull
statusenumactiveinactivesuspended
voiceobject | null
voiceId reqstring
provider reqstring
metadataobject
firstLoginAtstring
usernamestring | null
preferencesany
assistantNamestring | null
appNamestring | null
createdAtstring
updatedAtstring
type reqenumemailphoneexternal_idemployee_idgooglemicrosoftapplecustom
value reqstring
verified reqboolean
primary reqboolean
labelstring | null
platformsobject
metadataobject
iMessageCapableboolean | null
whatsAppCapableboolean | null
preferredTextPlatformenumimessagesmswhatsappnull
messagingWindowobject
whatsappobject
warmUntilstring | null
lastInboundAtstring | null
imessageobject
warmUntilstring | null
lastInboundAtstring | null
createdAt reqstring
updatedAtstring
400Invalid value (invalid_phone for an unparseable number), or the value is held by another user in your account
status reqinteger
error_codestring
error reqstring

Request

curl 'https://api.agnt.ai/identifiers' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "type": "email",
  "value": "value"
}'

Response

{
  "ok": true,
  "identifier": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "account": "account",
    "user": {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "account": "account",
      "assistant": "assistant",
      "name": "Ava",
      "avatarUrl": "https://example.com",
      "timezone": "America/New_York"
    },
    "type": "email",
    "value": "value",
    "verified": true
  }
}
GET/identifiers/{identifierId}

Retrieve an identifier

Retrieves an identifier.

Path parameters

identifierId reqstring

Responses

200Identifier detail
ok reqenumtrue
identifier reqobject
id reqstring
account reqstring
user reqobject
idstring
accountstring
emailstring
externalIdstring
assistantstring | null
namestring | null
firstNamestring
lastNamestring
avatarUrlstring | null
timezonestring
localestring
countrystring | null
citystring
organizationstring | null
organizationRoleenumadminmemberguest
teamany
teamRoleenummemberadminownernull
statusenumactiveinactivesuspended
voiceobject | null
voiceId reqstring
provider reqstring
metadataobject
firstLoginAtstring
usernamestring | null
preferencesany
assistantNamestring | null
appNamestring | null
createdAtstring
updatedAtstring
type reqenumemailphoneexternal_idemployee_idgooglemicrosoftapplecustom
value reqstring
verified reqboolean
primary reqboolean
labelstring | null
platformsobject
metadataobject
iMessageCapableboolean | null
whatsAppCapableboolean | null
preferredTextPlatformenumimessagesmswhatsappnull
messagingWindowobject
whatsappobject
warmUntilstring | null
lastInboundAtstring | null
imessageobject
warmUntilstring | null
lastInboundAtstring | null
createdAt reqstring
updatedAtstring
404Not found
status reqinteger
error_codestring
error reqstring

Request

curl 'https://api.agnt.ai/identifiers/<identifierId>' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "identifier": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "account": "account",
    "user": {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "account": "account",
      "assistant": "assistant",
      "name": "Ava",
      "avatarUrl": "https://example.com",
      "timezone": "America/New_York"
    },
    "type": "email",
    "value": "value",
    "verified": true
  }
}
PUT/identifiers/{identifierId}

Update an identifier

Updates an identifier's `verified` flag, label, platforms and metadata. To change the value, create a new identifier.

Path parameters

identifierId reqstring

Request body

verifiedboolean
labelstring | null
platformsobject
metadataobject

Responses

200Updated
ok reqenumtrue
identifier reqobject
id reqstring
account reqstring
user reqobject
idstring
accountstring
emailstring
externalIdstring
assistantstring | null
namestring | null
firstNamestring
lastNamestring
avatarUrlstring | null
timezonestring
localestring
countrystring | null
citystring
organizationstring | null
organizationRoleenumadminmemberguest
teamany
teamRoleenummemberadminownernull
statusenumactiveinactivesuspended
voiceobject | null
voiceId reqstring
provider reqstring
metadataobject
firstLoginAtstring
usernamestring | null
preferencesany
assistantNamestring | null
appNamestring | null
createdAtstring
updatedAtstring
type reqenumemailphoneexternal_idemployee_idgooglemicrosoftapplecustom
value reqstring
verified reqboolean
primary reqboolean
labelstring | null
platformsobject
metadataobject
iMessageCapableboolean | null
whatsAppCapableboolean | null
preferredTextPlatformenumimessagesmswhatsappnull
messagingWindowobject
whatsappobject
warmUntilstring | null
lastInboundAtstring | null
imessageobject
warmUntilstring | null
lastInboundAtstring | null
createdAt reqstring
updatedAtstring

Request

curl 'https://api.agnt.ai/identifiers/<identifierId>' \
  -X PUT \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "verified": true,
  "label": "label",
  "platforms": {},
  "metadata": {}
}'

Response

{
  "ok": true,
  "identifier": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "account": "account",
    "user": {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "account": "account",
      "assistant": "assistant",
      "name": "Ava",
      "avatarUrl": "https://example.com",
      "timezone": "America/New_York"
    },
    "type": "email",
    "value": "value",
    "verified": true
  }
}
DELETE/identifiers/{identifierId}

Delete an identifier

Deletes an identifier. A user's last identifier and their primary email cannot be deleted.

Path parameters

identifierId reqstring

Responses

200Deleted
ok reqenumtrue
identifier reqobject
id reqstring
deletedboolean
messagestring

Request

curl 'https://api.agnt.ai/identifiers/<identifierId>' \
  -X DELETE \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "identifier": {
    "id": "6660c4a1f2e3b7d8a9c01234"
  }
}
POST/identifiers/{identifierId}/link

Link an identifier to a user

Attaches the identifier to the user given by `userId`.

Path parameters

identifierId reqstring

Request body

userId reqstring

Responses

200Linked
ok reqenumtrue
identifier reqobject
id reqstring
account reqstring
user reqobject
idstring
accountstring
emailstring
externalIdstring
assistantstring | null
namestring | null
firstNamestring
lastNamestring
avatarUrlstring | null
timezonestring
localestring
countrystring | null
citystring
organizationstring | null
organizationRoleenumadminmemberguest
teamany
teamRoleenummemberadminownernull
statusenumactiveinactivesuspended
voiceobject | null
voiceId reqstring
provider reqstring
metadataobject
firstLoginAtstring
usernamestring | null
preferencesany
assistantNamestring | null
appNamestring | null
createdAtstring
updatedAtstring
type reqenumemailphoneexternal_idemployee_idgooglemicrosoftapplecustom
value reqstring
verified reqboolean
primary reqboolean
labelstring | null
platformsobject
metadataobject
iMessageCapableboolean | null
whatsAppCapableboolean | null
preferredTextPlatformenumimessagesmswhatsappnull
messagingWindowobject
whatsappobject
warmUntilstring | null
lastInboundAtstring | null
imessageobject
warmUntilstring | null
lastInboundAtstring | null
createdAt reqstring
updatedAtstring

Request

curl 'https://api.agnt.ai/identifiers/<identifierId>/link' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "6660c4a1f2e3b7d8a9c01234"
}'

Response

{
  "ok": true,
  "identifier": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "account": "account",
    "user": {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "account": "account",
      "assistant": "assistant",
      "name": "Ava",
      "avatarUrl": "https://example.com",
      "timezone": "America/New_York"
    },
    "type": "email",
    "value": "value",
    "verified": true
  }
}
POST/identifiers/{identifierId}/make-primary

Make an email primary

Makes an email identifier the user's primary email, which changes the user's `email`. Only email identifiers can be primary.

Path parameters

identifierId reqstring

Responses

200Result
ok reqenumtrue
makePrimary reqobject
user reqobject
id reqstring
account reqstring
emailstring
externalIdstring
assistant reqstring | null
name reqstring | null
firstNamestring
lastNamestring
avatarUrl reqstring | null
timezone reqstring
locale reqstring
countrystring | null
citystring
organization reqstring | null
organizationRole reqenumadminmemberguest
team reqobject | null
id reqstring
name reqstring
organization reqstring | null
status reqstring
teamRole reqenummemberadminownernull
status reqenumactiveinactivesuspended
voiceobject | null
voiceId reqstring
provider reqstring
metadataobject
firstLoginAtstring
usernamestring | null
preferencesobject
remindersany
preferredProvidersobject
preferredContactChannelobject
assistantNamestring | null
appNamestring | null
createdAt reqstring
updatedAt reqstring
identifier reqobject
id reqstring
type reqenumemailphoneexternal_idemployee_idgooglemicrosoftapplecustom
value reqstring
verified reqboolean
primary reqboolean
400The identifier is not an email

Request

curl 'https://api.agnt.ai/identifiers/<identifierId>/make-primary' \
  -X POST \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "makePrimary": {
    "user": {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "account": "account",
      "assistant": "assistant",
      "name": "Ava",
      "avatarUrl": "https://example.com",
      "timezone": "America/New_York"
    },
    "identifier": {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "type": "email",
      "value": "value",
      "verified": true,
      "primary": true
    }
  }
}