Leads · Couplr Developers

Base URL: https://couplrfsm.com/api/v1. Conventions shared by every endpoint (examples, ids, dates, money) are on the API reference page. Errors, pagination and idempotency are in Errors, limits and retries.

List leads#

GET /api/v1/leads · requires the leads:read ability

Query parameters

Name	Type	Required	Description
`page`	integer	No	Default: `1`.
`per_page`	integer	No	Values above 100 are served as 100. Default: `25`.
`updated_since`	string (date-time)	No	Only records changed at or after this time. ISO 8601, for example `2026-11-14T15:00:00Z`.
`channel`	string	No	Exact match, e.g. `sms`, `web_chat`, `voice`.
`status`	string	No
`created_from`	string (date)	No

Example request

curl "https://couplrfsm.com/api/v1/leads" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response (200)

{
    "data": [
        {
            "id": "01a1db67-3ef9-73f3-bf60-4e522919bef6",
            "channel": "sms",
            "status": "active",
            "phone": "5552018890",
            "zip": "74105",
            "customer_id": 1842,
            "collected": {
                "issue": "No cooling upstairs"
            },
            "last_inbound_at": "2026-11-14T15:00:02+00:00",
            "last_outbound_at": "2026-11-14T15:00:09+00:00",
            "created_at": "2026-11-14T14:58:30+00:00",
            "updated_at": "2026-11-14T15:00:09+00:00"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    }
}

Errors

Status	When
`401`	No key (`api_key_missing`), the key is unknown or revoked (`api_key_invalid`), the key had an end date that has passed (`api_key_expired`), or the key belongs to a private trial sandbox whose access window has ended (`sandbox_expired`).
`403`	The key lacks the ability this endpoint needs (`ability_missing`), no admin user is left to act for the key (`no_acting_admin`), or the company's account is not yet verified.
`422`	A parameter or field is invalid (`validation_failed`). `errors` maps each field to its messages.
`429`	Too many requests (`rate_limited`). Wait `Retry-After` seconds.

Create a lead#

POST /api/v1/leads · requires the leads:write ability · accepts Idempotency-Key

Adds a lead. The person is matched to an existing customer by phone number, or added as a new customer, and the lead appears in Speed to Lead with a note for the office to follow up by phone.

By default nobody is texted. To have Couplr's assistant open a text conversation with the person, send both "start_conversation": true and "sms_consent": true. Send sms_consent only when the person has agreed to receive texts from this company. A conversation that ends with the assistant booking a visit counts as one booked lead on the account's plan, the same as a lead from the website form.

Even when asked, no text is sent if texting is not set up for the account, the person has replied STOP before, or the number is not a US or Canadian one. The lead is still created, and the response says why in conversation_not_started_reason.

Each call creates a lead. Send an Idempotency-Key so a retry does not create a second one.

Headers

Name	Type	Required	Description
`Idempotency-Key`	string	No	Makes a retry of this request safe. See "Retries and idempotency".

Request body (application/json)

Fields not listed are ignored.

Field	Type	Required	Description
`name`	string	Yes
`phone`	string	Yes	At least ten digits. Punctuation is ignored.
`zip`	string or null	No	Used to check the lead is inside the company's service area.
`start_conversation`	boolean	No	Have the assistant text this person to start a Speed to Lead conversation. Needs `sms_consent`. Default: `false`.
`sms_consent`	boolean	No	True only when this person has agreed to receive texts from the company. Required when `start_conversation` is true. Default: `false`.

Example request

curl -X POST "https://couplrfsm.com/api/v1/leads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY" \
  -d '{"name":"Dana Whitfield","phone":"555-201-8890","zip":"74105"}'

Example response (201)

{
    "data": {
        "id": "01a1db67-3ef9-73f3-bf60-4e522919bef6",
        "channel": "sms",
        "status": "active",
        "phone": "5552018890",
        "zip": "74105",
        "customer_id": 1842,
        "collected": {
            "issue": "No cooling upstairs"
        },
        "last_inbound_at": "2026-11-14T15:00:02+00:00",
        "last_outbound_at": "2026-11-14T15:00:09+00:00",
        "created_at": "2026-11-14T14:58:30+00:00",
        "updated_at": "2026-11-14T15:00:09+00:00"
    }
}

Errors

Status	When
`401`	No key (`api_key_missing`), the key is unknown or revoked (`api_key_invalid`), the key had an end date that has passed (`api_key_expired`), or the key belongs to a private trial sandbox whose access window has ended (`sandbox_expired`).
`403`	The key lacks the ability this endpoint needs (`ability_missing`), no admin user is left to act for the key (`no_acting_admin`), or the company's account is not yet verified.
`422`	A parameter or field is invalid (`validation_failed`). `errors` maps each field to its messages.
`429`	Too many requests (`rate_limited`). Wait `Retry-After` seconds.

Get a lead#

GET /api/v1/leads/{id} · requires the leads:read ability

Path parameters

Name	Type	Required	Description
`id`	string (uuid)	Yes

Example request

curl "https://couplrfsm.com/api/v1/leads/9d3f6a52-0c1e-4c57-9d0a-3a0f8a4a7b21" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response (200)

{
    "data": {
        "id": "01a1db67-3ef9-73f3-bf60-4e522919bef6",
        "channel": "sms",
        "status": "active",
        "phone": "5552018890",
        "zip": "74105",
        "customer_id": 1842,
        "collected": {
            "issue": "No cooling upstairs"
        },
        "last_inbound_at": "2026-11-14T15:00:02+00:00",
        "last_outbound_at": "2026-11-14T15:00:09+00:00",
        "created_at": "2026-11-14T14:58:30+00:00",
        "updated_at": "2026-11-14T15:00:09+00:00"
    }
}

Errors

Status	When
`401`	No key (`api_key_missing`), the key is unknown or revoked (`api_key_invalid`), the key had an end date that has passed (`api_key_expired`), or the key belongs to a private trial sandbox whose access window has ended (`sandbox_expired`).
`403`	The key lacks the ability this endpoint needs (`ability_missing`), no admin user is left to act for the key (`no_acting_admin`), or the company's account is not yet verified.
`404`	No such record in this company (`not_found`).
`429`	Too many requests (`rate_limited`). Wait `Retry-After` seconds.

Lead object#

Field	Type	Description
`id`	string (uuid)
`channel`	string or null
`status`	string or null
`phone`	string or null
`zip`	string or null
`customer_id`	integer or null
`collected`	object or null	Whatever the assistant captured. Keys vary by lead.
`last_inbound_at`	string (date-time) or null
`last_outbound_at`	string (date-time) or null
`created_at`	string (date-time) or null
`updated_at`	string (date-time) or null