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.
/api/v1/contactsAuthorization
BearerAuth 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.
Response Body
application/json
application/json
application/json
application/json
application/json
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."}/api/v1/contactsAuthorization
BearerAuth Pass an API key issued from the agentlyleads workspace settings.
Example: Authorization: Bearer alk_live_xxxxxxxxxxxx
In: header
Query Parameters
Filter to contacts with this exact email address.
Filter to the contact with this external ID.
Filter to contacts linked to the company with this external ID.
Only contacts updated at or after this ISO 8601 datetime.
date-timePage size.
1 <= value <= 1000100The nextCursor value from the previous page.
Response Body
application/json
application/json
application/json
application/json
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."}