Diese Seite wurde noch nicht in Ihre Sprache übersetzt. Angezeigt wird die Version Englisch (Vereinigtes Königreich).
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
404with "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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
page | Query | integer | No | Page number, starting at 1 |
limit | Query | integer | No | 1 to 100. Default 25 |
search | Query | string | No | Up to 200 characters, matched against first name, last name, full name, company name, email and phone number |
crmStatus | Query | string | No | lead, potential, bad_timing, client or unqualified |
assigneeIds | Query | string or string[] | No | Admins only: leads owned by any of these people (comma-separated or repeated). A member always sees only their own |
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
assigneeIds | Query | string or string[] | No | Admins only: count across these people. Ignored for members |
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.
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
leadId | Path | integer | Yes | The id of the lead |
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
leadId | Path | integer | Yes | The id of the lead |
limit | Query | integer | No | 1 to 100. Default 20 |
offset | Query | integer | No | Entries to skip. Continue with nextOffset |
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
firstName | Body | string | Yes | First name |
lastName | Body | string | Yes | Last name |
email | Body | string | Yes | Email address |
phoneNumber | Body | string | Yes | Phone number |
crmStatus | Body | string | Yes | lead, potential, bad_timing, client or unqualified |
companyName | Body | string | No | Up to 255 characters |
language | Body | string | No | The lead's language, for example en-GB |
assigneeIds | Body | string or string[] | No | Admins only: owners other than the key's person |
teamIds | Body | UUID or UUID[] | No | Admins only: give the lead to every member of these teams |
unassigned | Body | boolean | No | Admins only: create the lead with no owner |
The 201 response wraps the new lead:
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
leadId | Path | integer | Yes | The id of the lead |
firstName | Body | string | No | First name |
lastName | Body | string | No | Last name |
email | Body | string | No | Email address |
phoneNumber | Body | string | No | Phone number |
companyName | Body | string or null | No | Up to 255 characters |
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
leadId | Path | integer | Yes | The id of the lead |
crmStatus | Body | string | Yes | lead, potential, bad_timing, client or unqualified |
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
leadIds | Body | integer[] | Yes | 1 to 500 lead ids |
crmStatus | Body | string | Yes | The new status |
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
leadIds | Body | integer[] | Yes | 1 to 500 lead ids |
addTagIds | Body | UUID[] | No | Tags to add |
removeTagIds | Body | UUID[] | No | Tags to take off |
Send at least one tag to add or remove.
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
leadIds | Body | integer[] | Yes | 1 to 500 lead ids |
title | Body | string | Yes | The task's title |
description | Body | string | No | A longer description |
dueDate | Body | string | No | YYYY-MM-DD for a day, or a full ISO timestamp |
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
leadIds | Body | integer[] | Yes | 1 to 500 lead ids |
userIds | Body | string[] | Yes | Person ids from List members |
teamIds | Body | UUID or UUID[] | No | Teams from List teams |
mode | Body | string | Yes | replace or add |
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
merges | Body | object[] | Yes | 1 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.
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
leadId | Path | integer | Yes | The id of the lead |
tagIds | Body | UUID[] | Yes | The full new set of tags |
The response is the lead, with the tag in tags:
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
leadId | Path | integer | Yes | The id of the lead |
userIds | Body | string[] | Yes | Person ids from List members |
teamIds | Body | UUID or UUID[] | No | Teams from List teams |
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.
The response wraps the lead, as above. Errors: 403 with ORG_ADMIN_REQUIRED for a member's key.