API Reference

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

POST/api/v1/leads

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.

name*string

Full name of the person.

Length1 <= length <= 200

email?string

Email address. Also the dedupe key — if a lead with this email already exists in the workspace (matched case-insensitively), that lead is updated (non-empty fields are merged onto it) instead of a duplicate being created.

Formatemail

Lengthlength <= 254

phone?string

Phone number, any format.

Lengthlength <= 50

company?string

Company name (free text; matched to a CRM Company at conversion).

Lengthlength <= 200

source?string

Where the lead came from (attribution).

Lengthlength <= 200

sourceDetail?string

Attribution detail — e.g. the page URL, campaign, or referrer. Stored on the lead's notes as "Source detail: …".

Lengthlength <= 500

message?string

Free-text message from the person. Logged as the lead's first Communication NOTE so it shows on the lead's activity timeline.

Lengthlength <= 10000

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/leads" \  -H "Content-Type: application/json" \  -d '{    "name": "John Prospect"  }'

{  "lead": {    "id": "cmq5lead0alk34567890",    "name": "Jane Buyer",    "email": "jane@acme.com",    "phone": "+1 555 0100",    "company": "Acme Inc.",    "source": "Landing page",    "status": "NEW",    "estimatedInterest": "MEDIUM",    "notes": "string",    "ownerId": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  },  "updated": true}

{  "lead": {    "id": "cmq5lead0alk34567890",    "name": "Jane Buyer",    "email": "jane@acme.com",    "phone": "+1 555 0100",    "company": "Acme Inc.",    "source": "Landing page",    "status": "NEW",    "estimatedInterest": "MEDIUM",    "notes": "string",    "ownerId": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}

{  "error": "name is required."}

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

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

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

GET/api/v1/leads

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 the lead with this exact email address (case-insensitive).

externalId?string

Filter to the lead with this external ID.

status?string

Filter to leads in this pipeline status.

Value in

"NEW"
"WORKING"
"QUALIFIED"
"UNQUALIFIED"
"CONVERTED"

lifecycleStage?string

Filter to leads at this lifecycle stage.

Value in

"SUBSCRIBER"
"LEAD"
"MARKETING_QUALIFIED_LEAD"
"SALES_QUALIFIED_LEAD"
"OPPORTUNITY"
"CUSTOMER"
"EVANGELIST"
"OTHER"

updatedSince?string

Only leads 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/leads?email=jane%40acme.com&externalId=hs_lead_123"

{  "leads": [    {      "id": "cmq5lead0alk34567890",      "name": "Jane Buyer",      "title": "Head of Procurement",      "company": "Acme Inc.",      "email": "jane@acme.com",      "phone": "+1 555 0100",      "source": "Landing page",      "category": "string",      "buyerType": "string",      "website": "string",      "linkedinUrl": "string",      "city": "string",      "state": "string",      "country": "string",      "lifecycleStage": "SUBSCRIBER",      "status": "NEW",      "estimatedInterest": "MEDIUM",      "notes": "string",      "externalId": "hs_lead_123",      "owner": {        "name": "string",        "email": "rep@yourcompany.com"      },      "interestedOffering": {        "name": "Starter Plan",        "sku": "string",        "externalId": "hs_product_9"      },      "customFields": {},      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ],  "nextCursor": "string"}

{  "error": "status must be one of: NEW, WORKING, QUALIFIED, UNQUALIFIED, CONVERTED."}

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

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

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

POST/api/v1/leads/{id}/convert

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.

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/leads/string/convert"

{  "lead": {    "id": "string",    "status": "CONVERTED",    "convertedContactId": "string"  },  "contact": {    "id": "string",    "name": "string",    "email": "string",    "company": "string",    "status": "string"  }}

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

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

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

{  "error": "Only a qualified lead can be converted. Set its status to QUALIFIED first (it is NEW)."}

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

DELETE/api/v1/leads/{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 lead's AgentlyLeads ID, or its externalId.

Response Body

`application/json`

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

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

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

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

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

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

API Reference

200application/json

201application/json

400application/json

401application/json

403application/json

429application/json

200application/json

400application/json

401application/json

403application/json

429application/json

201application/json

401application/json

403application/json

404application/json

409application/json

429application/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`