Contacts API
GET /api/v1/contacts
Returns the workspace's contacts, sorted by createdAt descending (newest first). Each contact includes its linked company (name + external ID) when one is set. Requires the read:contacts scope (or * for full access).
Request
GET /api/v1/contacts HTTP/1.1
Host: agentlyleads.com
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxQuery parameters
| Parameter | Description |
|---|---|
email | Return only contacts with this exact email address |
externalId | Return only the contact with this external ID |
companyExternalId | Return only contacts linked to the company with this external ID |
updatedSince | ISO 8601 datetime — only contacts updated at or after this moment (useful for incremental sync) |
limit | Page size, 1–1000 (default 100) |
cursor | The nextCursor value from the previous page |
All parameters are optional and can be combined. Filters that match nothing return an empty list, not a 404.
Look up a contact by email:
GET /api/v1/contacts?email=jane@acme.com HTTP/1.1
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxAll contacts at a company, changed since July 1:
GET /api/v1/contacts?companyExternalId=hs_company_42&updatedSince=2026-07-01T00:00:00Z HTTP/1.1
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxResponse — 200
{
"contacts": [
{
"id": "cmq1abc2def3ghi4jkl5",
"name": "Jane Buyer",
"firstName": "Jane",
"lastName": "Buyer",
"title": "Head of Procurement",
"email": "jane@acme.com",
"phone": null,
"status": "ACTIVE",
"lifecycleStage": "OPPORTUNITY",
"source": "hubspot",
"category": null,
"buyerType": null,
"website": null,
"city": "Zurich",
"state": null,
"country": "CH",
"doNotContact": false,
"emailOptOut": false,
"emailStatus": "VALID",
"engagementScore": 72,
"lastContactedAt": "2026-07-18T09:12:00.000Z",
"lastActivityAt": "2026-07-20T14:03:00.000Z",
"externalId": "hs_contact_123",
"company": { "name": "Acme Corp", "externalId": "hs_company_42" },
"customFields": null,
"createdAt": "2026-06-01T12:00:00.000Z",
"updatedAt": "2026-07-20T14:03:00.000Z"
}
],
"nextCursor": null
}Pagination
Responses are cursor-paginated. When more rows exist beyond the requested limit, nextCursor holds the ID of the last returned record — pass it back as cursor to fetch the next page. On the last page, nextCursor is null.
GET /api/v1/contacts?limit=100&cursor=cmq1abc2def3ghi4jkl5 HTTP/1.1
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx