Leadnote public API: create, read and update leads

The Leadnote public API lets your own software add leads, read them back and change them. You need an API key with the right scopes; create one as described in API keys. Every call is for one organisation: the one that owns the key.

The examples use https://leadsnote.com as the base address. The API reference tab shows the base address for your account.

Authentication and limits

Send the key in the x-api-key header, or as Authorization: Bearer YOUR_API_KEY. The rate limit (60 requests a minute per key) and the Retry-After header are described in API keys.

Find the list key

Every list has a list key. Call the lists endpoint to see them, or open the API reference tab.

curl 'https://leadsnote.com/api/public/lists' \
  -H 'x-api-key: YOUR_API_KEY'

{ "data": [ { "id": "LIST_ID", "name": "Website enquiries", "listKey": "LIST_KEY" } ] }

Create a lead

curl -X POST 'https://leadsnote.com/api/public/leads' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'content-type: application/json' \
  -d '{"firstName":"Asha","email":"asha@example.com","phone":"+919876543210","listKey":"LIST_KEY"}'

A new lead answers with its id and a status of created:

{ "id": "LEAD_ID", "status": "created" }

If the email or phone already exists in your account, no new lead is made. The answer has the existing lead's id and the status duplicate.

Required: firstName, and at least one of email or phone.

Optional fields:

A listKey that matches no list is refused, so a typo never sends leads to the wrong place. New leads start in your default open stage, and Leadnote sends the same lead.created event as the app does.

List and read leads

curl 'https://leadsnote.com/api/public/leads?limit=25&page=1&listKey=LIST_KEY&updatedSince=2026-10-01T00:00:00Z' \
  -H 'x-api-key: YOUR_API_KEY'

The answer holds page, limit and a data array of leads with their id, names, email, phone, company, place, potential, stage id, list id, source, tags, notes and timestamps.

GET /api/public/leads/{id} returns one lead as flat JSON. It also has fullName, stageName and listName, and your custom field values as custom_<fieldKey>.

Update a lead

curl -X PATCH 'https://leadsnote.com/api/public/leads/LEAD_ID' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'content-type: application/json' \
  -d '{"potential":"high","notes":"Asked for a demo"}'

You can change names, email, phone, company, designation, website, address fields, potential, deal size, product group, customer group, tags, notes, custom fields, stageId and assignedToId. Send at least one field. Unknown fields and an empty body are refused rather than ignored. A phone number in a PATCH must include the country code, for example +919876543210.

The change goes through the same rules as an edit in the app, so stage history, the activity log, lead score and webhook events all update.

Errors

Errors always have one shape:

{ "error": { "code": "validation_error", "message": "Invalid request", "details": { "fieldErrors": { "email": ["email is not valid"] } } } }

A validation error lists the fields in details.fieldErrors. A missing or wrong key is refused as not authenticated, and a key without the needed scope is refused as not allowed. A suspended organisation cannot create leads.

Tools

• OpenAPI document: GET /api/public/docs returns the description of the API.
• Postman collection: download it from the API reference tab on the API and webhooks page.
• Webhooks: to be told when leads change instead of polling, see webhooks.
• Your own web form: a form on your website can post straight to the form's address without a key. See embed a form on your website.