API Reference

The reference below covers every endpoint in the Contacts API. Code examples are generated automatically; the live playground is disabled to prevent accidental writes to production from the docs site.

POST/api/v1/contacts

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

contacts*array<>

Items1 <= items <= 1000

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/contacts" \  -H "Content-Type: application/json" \  -d '{    "contacts": [      {        "name": "Jane Buyer",        "email": "jane@acme.com",        "companyExternalId": "SHOP-CO-1",        "externalId": "SHOP-C-1"      }    ]  }'

{  "created": 1,  "updated": 1,  "errors": 0,  "results": [    {      "index": 0,      "status": "created",      "id": "018e2a4b-0000-7000-8000-aabbccddeeff"    },    {      "index": 1,      "status": "updated",      "id": "018e2a4b-1111-7000-8000-aabbccddeeff"    }  ]}

{  "created": 1,  "updated": 0,  "errors": 1,  "results": [    {      "index": 0,      "status": "created",      "id": "018e2a4b-0000-7000-8000-aabbccddeeff"    },    {      "index": 1,      "status": "error",      "error": "companyExternalId: no company found for \"NOPE\"."    }  ]}

{  "error": "contacts must not be empty."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:products."}

{  "error": "Rate limit exceeded."}

GET/api/v1/contacts

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Query Parameters

email?string

Filter to contacts with this exact email address.

externalId?string

Filter to the contact with this external ID.

companyExternalId?string

Filter to contacts linked to the company with this external ID.

updatedSince?string

Only contacts updated at or after this ISO 8601 datetime.

Formatdate-time

limit?integer

Page size.

Range1 <= value <= 1000

Default100

cursor?string

The nextCursor value from the previous page.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/contacts?email=jane%40acme.com&externalId=hs_contact_123"

{  "contacts": [    {      "id": "cmq1abc2def3ghi4jkl5",      "name": "Jane Buyer",      "firstName": "string",      "lastName": "string",      "title": "Head of Procurement",      "email": "jane@acme.com",      "phone": "string",      "status": "NEW",      "lifecycleStage": "SUBSCRIBER",      "source": "string",      "category": "string",      "buyerType": "string",      "website": "string",      "city": "string",      "state": "string",      "country": "string",      "doNotContact": true,      "emailOptOut": true,      "emailStatus": "string",      "engagementScore": 0,      "lastContactedAt": "2019-08-24T14:15:22Z",      "lastActivityAt": "2019-08-24T14:15:22Z",      "externalId": "hs_contact_123",      "company": {        "name": "Acme Corp",        "externalId": "hs_company_42"      },      "customFields": {},      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ],  "nextCursor": "string"}

{  "error": "updatedSince must be an ISO 8601 datetime."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: read:contacts."}

{  "error": "Rate limit exceeded."}

GET/api/v1/contacts/duplicates

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Query Parameters

limit?integer

Pairs to return, 1 to 100 (default 25).

Range1 <= value <= 100

Default25

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/contacts/duplicates"

{  "duplicates": [    {      "a": {        "id": "string",        "name": "string",        "email": "string",        "company": "string"      },      "b": {        "id": "string",        "name": "string",        "email": "string",        "company": "string"      },      "reason": "same name"    }  ]}

{  "error": "limit must be an integer between 1 and 100."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: read:contacts."}

{  "error": "Rate limit exceeded."}

POST/api/v1/contacts/{id}/merge

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

Survivor: agentlyleads ID or externalId.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

duplicateId*string

The contact merged in and deleted (ID or externalId).

confirm*boolean

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/contacts/string/merge" \  -H "Content-Type: application/json" \  -d '{    "duplicateId": "string",    "confirm": true  }'

{  "survivorId": "string",  "survivorName": "string",  "deletedId": "string",  "repointed": 0,  "collisionsDropped": 0}

{  "error": "A contact can't be merged into itself."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:contacts."}

{  "error": "Duplicate contact not found."}

{  "error": "Rate limit exceeded."}

POST/api/v1/contacts/{id}/brief

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

agentlyleads ID or externalId.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

asUserEmail?string

Formatemail

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/contacts/string/brief" \  -H "Content-Type: application/json" \  -d '{}'

{  "brief": {    "id": "string",    "contactId": "string",    "summary": "string",    "engagementScore": 0,    "recommendedAction": "string",    "draftMessage": "string",    "profileSuggestions": [      {        "field": "string",        "value": "string",        "reason": "string"      }    ],    "model": "string",    "generatedAt": "2019-08-24T14:15:22Z"  }}

{  "error": "Invalid or missing API key."}

{  "error": "This workspace has used its 25 AI actions for the month. They reset on October 1."}

{  "error": "API key missing required scope: write:contacts."}

{  "error": "Contact not found."}

{  "error": "Rate limit exceeded."}

{  "error": "We couldn't generate a brief right now. Please try again."}

DELETE/api/v1/contacts/{id}

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The contact's AgentlyLeads ID, or its externalId.

Response Body

`application/json`

curl -X DELETE "https://example.com/api/v1/contacts/string"

{  "deleted": 1,  "id": "cmq2cont0alk34567891"}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:contacts."}

{  "error": "Contact not found."}

{  "error": "Rate limit exceeded."}

API Reference

200application/json

207application/json

400application/json

401application/json

403application/json

429application/json

200application/json

400application/json

401application/json

403application/json

429application/json

200application/json

400application/json

401application/json

403application/json

429application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

201application/json

401application/json

402application/json

403application/json

404application/json

429application/json

502application/json

200application/json

401application/json

403application/json

404application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`