Couplr Couplr developers
OpenAPI llms.txt Couplr
API v1 · API reference · explained by Flip

Customers

List, find, create and update customers, and add service addresses to them.

View Markdown

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 customers#

GET /api/v1/customers · requires the customers: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.
search string No Matches part of a name, alternate name, email or phone.
email string No Exact email match.
phone string No Matches part of the phone number; non-digits are ignored.

Example request

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

Example response (200)

{
    "data": [
        {
            "id": 1842,
            "name": "Dana Whitfield",
            "email": "dana@example.com",
            "phone": "5552018890",
            "phone_is_mobile": true,
            "addresses": [
                {
                    "id": 2210,
                    "address": "412 Larkspur Ln",
                    "city": "Tulsa",
                    "state": "OK",
                    "zip_code": "74105"
                }
            ],
            "created_at": "2026-11-14T15:02:11+00:00",
            "updated_at": "2026-11-14T15:02:11+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 customer#

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

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. email is required unless uses_email is false.

Field Type Required Description
name string Yes
email string (email) or null No
uses_email boolean No false records that the customer has no email.
phone string Yes Any format; stored as digits.
phone_is_mobile boolean No
address string or null No Updates the customer's primary address.
city string or null No
state string or null No
zip_code string or null No
sms_consent boolean No Send only when the customer has agreed to receive texts. true records consent only when none is on file, and never clears an opt-out the customer made by texting STOP; only the customer can undo that, by texting START. false opts the customer out.
send_card_request boolean No true emails the customer a request to put a card on file. Default: false.
ignore_duplicates boolean No false returns 409 with candidates when the name or address matches an existing customer. Default: true.

Example request

curl -X POST "https://couplrfsm.com/api/v1/customers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY" \
  -d '{"name":"Dana Whitfield","email":"dana@example.com","phone":"(555) 201-8890","address":"412 Larkspur Ln","city":"Tulsa","state":"OK","zip_code":"74105"}'

Example response (201)

{
    "data": {
        "id": 1842,
        "name": "Dana Whitfield",
        "email": "dana@example.com",
        "phone": "5552018890",
        "phone_is_mobile": true,
        "addresses": [
            {
                "id": 2210,
                "address": "412 Larkspur Ln",
                "city": "Tulsa",
                "state": "OK",
                "zip_code": "74105"
            }
        ],
        "created_at": "2026-11-14T15:02:11+00:00",
        "updated_at": "2026-11-14T15:02:11+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.
409 Only when ignore_duplicates is false: a customer with the same name or address exists. The body lists up to 5 candidates under duplicates, each a Customer plus matched_on (what collided). Nothing was created.
422 Validation failed, including an email (or, with uses_email: false, a phone) that already belongs to another customer.
429 Too many requests (rate_limited). Wait Retry-After seconds.

Get a customer#

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

Path parameters

Name Type Required Description
id integer Yes

Example request

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

Example response (200)

{
    "data": {
        "id": 1842,
        "name": "Dana Whitfield",
        "email": "dana@example.com",
        "phone": "5552018890",
        "phone_is_mobile": true,
        "addresses": [
            {
                "id": 2210,
                "address": "412 Larkspur Ln",
                "city": "Tulsa",
                "state": "OK",
                "zip_code": "74105"
            }
        ],
        "created_at": "2026-11-14T15:02:11+00:00",
        "updated_at": "2026-11-14T15:02:11+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.

Update a customer#

PATCH /api/v1/customers/{id} · requires the customers:write ability · accepts Idempotency-Key

Only the fields you send change.

Path parameters

Name Type Required Description
id integer Yes

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 No
email string (email) or null No
uses_email boolean No false records that the customer has no email.
phone string No Any format; stored as digits.
phone_is_mobile boolean No
address string or null No Updates the customer's primary address.
city string or null No
state string or null No
zip_code string or null No
sms_consent boolean No Send only when the customer has agreed to receive texts. true records consent only when none is on file, and never clears an opt-out the customer made by texting STOP; only the customer can undo that, by texting START. false opts the customer out.

Example request

curl -X PATCH "https://couplrfsm.com/api/v1/customers/1842" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY" \
  -d '{"phone":"(555) 201-7700"}'

Example response (200)

{
    "data": {
        "id": 1842,
        "name": "Dana Whitfield",
        "email": "dana@example.com",
        "phone": "5552018890",
        "phone_is_mobile": true,
        "addresses": [
            {
                "id": 2210,
                "address": "412 Larkspur Ln",
                "city": "Tulsa",
                "state": "OK",
                "zip_code": "74105"
            }
        ],
        "created_at": "2026-11-14T15:02:11+00:00",
        "updated_at": "2026-11-14T15:02:11+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).
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.

Add an address to a customer#

POST /api/v1/customers/{id}/addresses · requires the customers:write ability · accepts Idempotency-Key

Adds another service address, such as a rental or a second property. Use its id as address_id when creating a job.

Path parameters

Name Type Required Description
id integer Yes

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
address string Yes Street address.
city string or null No
state string or null No
zip_code string or null No

Example request

curl -X POST "https://couplrfsm.com/api/v1/customers/1842/addresses" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY" \
  -d '{"address":"88 Rental Row","city":"Tulsa","state":"OK","zip_code":"74104"}'

Example response (201)

{
    "data": {
        "id": 2211,
        "address": "88 Rental Row",
        "city": "Tulsa",
        "state": "OK",
        "zip_code": "74104"
    }
}

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).
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.

Customer object#

Field Type Description
id integer
name string
email string or null
phone string or null Digits only.
phone_is_mobile boolean
addresses array of objects
created_at string (date-time) or null
updated_at string (date-time) or null

Address object#

Field Type Description
id integer
address string or null
city string or null
state string or null
zip_code string or null

Copy this page as Markdown

Your browser blocked automatic copying. The complete page is selected below. Press Ctrl+C (Cmd+C on a Mac) to copy it.