This page hasn't been translated for your language. Showing the English (United Kingdom) version.

Leads

List, read, create and update leads, move them between statuses, set their tags and owners one at a time or many at once, and read their timeline through the Fondaro API.

Leads are the people in your CRM. These routes use the scopes crm:read (reading) and crm:write (changing). Writes also need an active Fondaro plan; without one they answer 403 with SUBSCRIPTION_REQUIRED.

The key acts as the person who made it:

  • A member reaches only the leads they own. A lead that is not theirs answers 404 with "Lead not found.", the same as a lead that does not exist.
  • An admin reaches every lead of the agency. Only an admin can assign owners, move many leads at once, or create a lead for someone else.

Send Authorization: Bearer $FONDARO_API_KEY on every call. Pages that list rows follow Errors and limits for paging. Lead ids are integers.

A status change (single or bulk), an assignee change, and a lead's opening status and owner when you create it through the API are recorded in the lead's history with the source value api, so the lead's timeline shows it as an API change made by the key's person.

List leads

GET /v1/leads

A page of leads, newest first, with their tags. A member sees only their own leads.

ParameterInTypeRequiredDescription
pageQueryintegerNoPage number, starting at 1
limitQueryintegerNo1 to 100. Default 25
searchQuerystringNoUp to 200 characters, matched against first name, last name, full name, company name, email and phone number
crmStatusQuerystringNolead, potential, bad_timing, client or unqualified
assigneeIdsQuerystring or string[]NoAdmins only: leads owned by any of these people (comma-separated or repeated). A member always sees only their own
bash
curl "https://api.fondaro.com/v1/leads?limit=3" \  -H "Authorization: Bearer $FONDARO_API_KEY"
json
{  "data": [    {      "id": 3438,      "firstName": "David",      "lastName": "Cohen",      "email": "david.cohen@example.com",      "phoneNumber": "+15624528939",      "language": "en-GB",      "companyName": null,      "crmStatus": "lead",      "assigneeIds": ["user_2abcDEF1234567890ghiJKL"],      "purchasedAt": "2026-10-01T05:42:00.000Z",      "totalCalls": 0,      "lastCallAt": null,      "pendingTasks": 2,      "nextTaskDueAt": "2026-10-01T07:30:00.000Z",      "leadGroup": null,      "tags": []    }  ],  "hasMore": true,  "page": 1,  "limit": 3,  "total": 29}

Paging is by page number; total is exact. Errors: 400 for a limit over 100 or an unknown crmStatus.

Count leads per status

GET /v1/leads/counts

The number of leads in each status. A member counts only their own leads; an admin counts the whole agency and also gets an unassigned bucket.

ParameterInTypeRequiredDescription
assigneeIdsQuerystring or string[]NoAdmins only: count across these people. Ignored for members
bash
curl https://api.fondaro.com/v1/leads/counts \  -H "Authorization: Bearer $FONDARO_API_KEY"
json
{ "lead": 6, "potential": 12, "bad_timing": 1, "client": 9, "unqualified": 1, "unassigned": 0 }

List duplicate leads

GET /v1/leads/duplicates

Groups of leads that share an email address or a phone number, oldest first. Each group says what it matches on (matchType: email, phone or both) and lists its leads. An answer carries as many groups as fit, at most 50; totalGroups and omittedGroups say how many more there are, so merge some and call again. A member sees only groups among the leads they own; an admin, the whole agency. Needs crm:read.

bash
curl https://api.fondaro.com/v1/leads/duplicates \  -H "Authorization: Bearer $FONDARO_API_KEY"
json
{  "groups": [    {      "matchType": "email",      "leads": [        { "id": 1042, "firstName": "Maria", "lastName": "Lopez", "email": "maria@example.com", "phoneNumber": "+34600111222", "crmStatus": "lead", "assigneeIds": ["user_2abcDEF1234567890ghiJKL"], "createdAt": "2026-03-02T09:14:00.000Z" },        { "id": 1187, "firstName": "Maria", "lastName": "López", "email": "maria@example.com", "phoneNumber": "", "crmStatus": "lead", "assigneeIds": ["user_2abcDEF1234567890ghiJKL"], "createdAt": "2026-05-19T16:40:00.000Z" }      ]    }  ],  "totalGroups": 1,  "omittedGroups": 0}

Get a lead

GET /v1/leads/{leadId}

One lead: contact details, status, tags, owners, call and task totals, and the chat channels linked to it. The history is on the timeline route.

ParameterInTypeRequiredDescription
leadIdPathintegerYesThe id of the lead
bash
curl https://api.fondaro.com/v1/leads/1042 \  -H "Authorization: Bearer $FONDARO_API_KEY"
json
{  "id": 1042,  "firstName": "Anna",  "lastName": "Berg",  "email": "anna@example.com",  "phoneNumber": "+46701234567",  "language": null,  "companyName": null,  "crmStatus": "lead",  "assigneeIds": ["user_2abcDEF1234567890ghiJKL"],  "totalCalls": 0,  "pendingTasks": 0,  "source": "manual",  "leadType": "buyer",  "tags": [],  "createdAt": "2026-10-04T12:02:03.718Z",  "channels": []}

Errors: 404 "Lead not found." for a lead that does not exist or is not yours. 400 for an id that is not an integer.

Get a lead timeline

GET /v1/leads/{leadId}/timeline

The lead's activity, newest first: notes, tasks, calls, emails, chat messages, meetings, viewings, documents, status changes, deal events, owner changes and how the lead was created. A very long body carries a _preview field that says what was shortened; the full text is on the calls and emails routes.

ParameterInTypeRequiredDescription
leadIdPathintegerYesThe id of the lead
limitQueryintegerNo1 to 100. Default 20
offsetQueryintegerNoEntries to skip. Continue with nextOffset
bash
curl "https://api.fondaro.com/v1/leads/1042/timeline?limit=5" \  -H "Authorization: Bearer $FONDARO_API_KEY"
json
{  "data": [    {      "type": "assignee-change",      "date": "2026-10-04T12:02:03.718Z",      "assigneeChange": {        "addedUserIds": ["user_2abcDEF1234567890ghiJKL"],        "removedUserIds": [],        "changedBy": "user_2abcDEF1234567890ghiJKL",        "source": "user"      }    },    { "type": "lead-created", "date": "2026-10-04T12:02:03.640Z", "leadCreated": { "source": "manual", "leadGroupName": null } }  ],  "hasMore": false,  "total": 2,  "totalIsExact": true,  "tasksById": {},  "dealsById": {}}

Paging is by offset. Errors: 404 "Lead not found."

Create a lead

POST /v1/leads

Creates a lead owned by the key's person. Only an admin can create an unassigned lead or one owned by someone else. Needs crm:write. Accepts an Idempotency-Key header.

ParameterInTypeRequiredDescription
firstNameBodystringYesFirst name
lastNameBodystringYesLast name
emailBodystringYesEmail address
phoneNumberBodystringYesPhone number
crmStatusBodystringYeslead, potential, bad_timing, client or unqualified
companyNameBodystringNoUp to 255 characters
languageBodystringNoThe lead's language, for example en-GB
assigneeIdsBodystring or string[]NoAdmins only: owners other than the key's person
teamIdsBodyUUID or UUID[]NoAdmins only: give the lead to every member of these teams
unassignedBodybooleanNoAdmins only: create the lead with no owner
bash
curl -X POST https://api.fondaro.com/v1/leads \  -H "Authorization: Bearer $FONDARO_API_KEY" \  -H "Idempotency-Key: 6f1c2d3e-0a4b-4c5d-8e9f-1a2b3c4d5e6f" \  -H "Content-Type: application/json" \  -d '{ "firstName": "Anna", "lastName": "Berg", "email": "anna@example.com", "phoneNumber": "+46701234567", "crmStatus": "lead" }'

The 201 response wraps the new lead:

json
{  "lead": {    "id": 1042,    "firstName": "Anna",    "lastName": "Berg",    "email": "anna@example.com",    "phoneNumber": "+46701234567",    "crmStatus": "lead",    "assigneeIds": ["user_2abcDEF1234567890ghiJKL"],    "source": "manual",    "leadType": "buyer",    "tags": [],    "createdAt": "2026-10-04T12:02:03.718Z"  }}

Errors: 400 for a missing field; 403 with FORBIDDEN ("Only org admins can create unassigned leads or assign them to others") when a member asks for another owner or an unassigned lead.

Update a lead's contact details

PATCH /v1/leads/{leadId}

Changes only the fields you send. A null or empty companyName clears it. Needs crm:write.

ParameterInTypeRequiredDescription
leadIdPathintegerYesThe id of the lead
firstNameBodystringNoFirst name
lastNameBodystringNoLast name
emailBodystringNoEmail address
phoneNumberBodystringNoPhone number
companyNameBodystring or nullNoUp to 255 characters
bash
curl -X PATCH https://api.fondaro.com/v1/leads/1042 \  -H "Authorization: Bearer $FONDARO_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "companyName": "Berg Holdings" }'

The response is the lead, as in Get a lead, with "companyName": "Berg Holdings". Errors: 404 "Lead not found."

Move a lead to another status

PUT /v1/leads/{leadId}/status

Sets the pipeline status. Needs crm:write.

ParameterInTypeRequiredDescription
leadIdPathintegerYesThe id of the lead
crmStatusBodystringYeslead, potential, bad_timing, client or unqualified
bash
curl -X PUT https://api.fondaro.com/v1/leads/1042/status \  -H "Authorization: Bearer $FONDARO_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "crmStatus": "potential" }'

The response is the lead with "crmStatus": "potential". The change is recorded with the source value api. Errors: 404 "Lead not found."

Move many leads to one status

POST /v1/leads/status

Sets the same status on up to 500 leads in one call. A member's key changes only the leads its person can see; an admin's, any lead of the agency. Needs crm:write.

ParameterInTypeRequiredDescription
leadIdsBodyinteger[]Yes1 to 500 lead ids
crmStatusBodystringYesThe new status
bash
curl -X POST https://api.fondaro.com/v1/leads/status \  -H "Authorization: Bearer $FONDARO_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "leadIds": [1042, 1043, 1044], "crmStatus": "potential" }'
json
{ "updated": 2, "changed": 1, "unchanged": 1, "skipped": 1, "skippedIds": [1044] }

changed is how many leads moved, unchanged how many were already at that status, updated the two together, and skippedIds the ids left out: not a lead of the agency, or not one the key's person can see. Each move is recorded with the source value api.

Change the tags on many leads

POST /v1/leads/tags

Adds and removes tags on up to 500 leads in one call; every other tag a lead has stays. A member's key changes only the leads its person can see; an admin's, any lead of the agency. Get tag ids from List tags. Needs crm:write.

ParameterInTypeRequiredDescription
leadIdsBodyinteger[]Yes1 to 500 lead ids
addTagIdsBodyUUID[]NoTags to add
removeTagIdsBodyUUID[]NoTags to take off

Send at least one tag to add or remove.

bash
curl -X POST https://api.fondaro.com/v1/leads/tags \  -H "Authorization: Bearer $FONDARO_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "leadIds": [1042, 1043], "addTagIds": ["3f6c2a10-0000-4000-8000-000000000006"] }'
json
{ "changed": 1, "unchanged": 1, "skipped": 0, "skippedIds": [] }

Errors: 404 for a tag id that isn't the agency's (nothing is changed).

Make the same task on many leads

POST /v1/leads/tasks

Makes one task per lead on up to 500 leads, each owned by the key's person. A member's key makes them only on the leads its person can see; an admin's, on any lead of the agency. Needs crm:write.

ParameterInTypeRequiredDescription
leadIdsBodyinteger[]Yes1 to 500 lead ids
titleBodystringYesThe task's title
descriptionBodystringNoA longer description
dueDateBodystringNoYYYY-MM-DD for a day, or a full ISO timestamp
bash
curl -X POST https://api.fondaro.com/v1/leads/tasks \  -H "Authorization: Bearer $FONDARO_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "leadIds": [1042, 1043], "title": "Call back", "dueDate": "2026-11-20" }'
json
{ "created": 2, "skipped": 0, "skippedIds": [] }

Assign many leads

POST /v1/leads/assignees

Admins only. Replaces the owners of up to 500 leads with the people, and the members of the teams, you send ("mode": "replace"), or adds them to each lead's owners ("mode": "add"). Needs crm:write.

ParameterInTypeRequiredDescription
leadIdsBodyinteger[]Yes1 to 500 lead ids
userIdsBodystring[]YesPerson ids from List members
teamIdsBodyUUID or UUID[]NoTeams from List teams
modeBodystringYesreplace or add
bash
curl -X POST https://api.fondaro.com/v1/leads/assignees \  -H "Authorization: Bearer $FONDARO_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "leadIds": [1042, 1043], "userIds": ["user_2abcDEF1234567890ghiJKL"], "mode": "add" }'
json
{ "changed": 2, "unchanged": 0, "skipped": 0, "skippedIds": [] }

Errors: 403 with ORG_ADMIN_REQUIRED for a member's key.

Merge duplicate leads

POST /v1/leads/merge

Folds each leadId into its intoLeadId, for 1 to 100 pairs: notes, tasks, calls, emails, messages, deals, tags and documents move to the kept lead, the owners and tags are combined, and the folded lead is deleted. This cannot be undone. The kept lead keeps its own name, email and phone. A member merges two leads only when both are theirs; an admin, any two. Needs crm:write.

ParameterInTypeRequiredDescription
mergesBodyobject[]Yes1 to 100 pairs, each { "leadId": 1187, "intoLeadId": 1042 }

Pairs run in order, each on its own, so a failing pair does not stop the others. A group of three duplicates is two pairs into the same intoLeadId. A call that merges a lead into itself, folds the same lead twice, or folds a lead that another pair keeps answers 400 and merges nothing.

bash
curl -X POST https://api.fondaro.com/v1/leads/merge \  -H "Authorization: Bearer $FONDARO_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "merges": [{ "leadId": 1187, "intoLeadId": 1042 }] }'
json
{ "merged": 1, "mergedPairs": [{ "leadId": 1187, "intoLeadId": 1042 }], "failed": [] }

A pair that did not merge is in failed with reason: not_found (a lead is missing or not one you can see), forbidden (a member who does not own both) or failed (an unexpected error, nothing moved for that pair).

Set the tags on a lead

PUT /v1/leads/{leadId}/tags

Replaces the lead's tags with exactly the tag ids you send. An empty list clears them. Get tag ids from List tags. Needs crm:write.

ParameterInTypeRequiredDescription
leadIdPathintegerYesThe id of the lead
tagIdsBodyUUID[]YesThe full new set of tags
bash
curl -X PUT https://api.fondaro.com/v1/leads/1042/tags \  -H "Authorization: Bearer $FONDARO_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "tagIds": ["3f6c2a10-0000-4000-8000-000000000006"] }'

The response is the lead, with the tag in tags:

json
{ "id": 1042, "tags": [{ "id": "3f6c2a10-0000-4000-8000-000000000006", "name": "BrandNewTag", "color": "slate", "leadCount": 1 }] }

Set the owners of a lead

PUT /v1/leads/{leadId}/assignees

Admins only. Replaces the lead's owners with the people, and the members of the teams, you send. An empty list leaves the lead unassigned. Needs crm:write.

ParameterInTypeRequiredDescription
leadIdPathintegerYesThe id of the lead
userIdsBodystring[]YesPerson ids from List members
teamIdsBodyUUID or UUID[]NoTeams from List teams
bash
curl -X PUT https://api.fondaro.com/v1/leads/1042/assignees \  -H "Authorization: Bearer $FONDARO_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "userIds": ["user_2abcDEF1234567890ghiJKL"] }'

The response wraps the lead: { "lead": { "id": 1042, "assigneeIds": ["user_2abcDEF1234567890ghiJKL"], … } }. Errors: 403 with ORG_ADMIN_REQUIRED for a member's key.

Add owners to a lead

POST /v1/leads/{leadId}/assignees

Admins only. Adds people, and the members of teams, to the lead's owners and keeps the existing ones. The parameters are the same as for setting owners. Needs crm:write.

bash
curl -X POST https://api.fondaro.com/v1/leads/1042/assignees \  -H "Authorization: Bearer $FONDARO_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "userIds": ["user_2mnoPQR1234567890stuVWX"] }'

The response wraps the lead, as above. Errors: 403 with ORG_ADMIN_REQUIRED for a member's key.