Quickstart

You need admin access to a Couplr company account.

1. Create an API key#

1. Sign in to Couplr on the web and open Integrations (https://couplrfsm.com/dashboard/integrations).
2. In the API keys section, create a new key. Name it after the app that will use it.
3. Check only the abilities the app needs. For this quickstart, check customers:read and customers:write.
4. Copy the key. It starts with hvp_ and is shown once. Couplr stores only a hash, so a lost key cannot be recovered, only replaced.

Keep the key on a server. Do not put it in a web page, a mobile app or a public repository.

2. Make a first request#

Replace YOUR_API_KEY with your key. GET /api/v1/me works with any valid key and tells you which company and abilities the key has.

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

Response (200):

{
  "company": "Summit Heat and Air",
  "key_name": "Zapier",
  "abilities": ["customers:read", "customers:write"],
  "test_mode": false
}

company, key_name and abilities will show your own values. test_mode is false for a key made on the Integrations page.

3. Create a customer#

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"}'

Response (201):

{
  "data": {
    "id": 1842,
    "name": "Dana Whitfield",
    "email": "dana@example.com",
    "phone": "5552018890",
    "phone_is_mobile": true,
    "addresses": [],
    "created_at": "2026-11-14T15:02:11+00:00",
    "updated_at": "2026-11-14T15:02:11+00:00"
  }
}

• Records come back inside data. Lists add meta with paging details.
• The phone number is stored as digits only.
• Idempotency-Key makes the request safe to retry. Send any unique string, such as a UUID. See Idempotency.
• Creating a customer through the API does not email the customer unless you send "send_card_request": true.

4. Read it back#

curl "https://couplrfsm.com/api/v1/customers?email=dana@example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200):

{
  "data": [
    {
      "id": 1842,
      "name": "Dana Whitfield",
      "email": "dana@example.com",
      "phone": "5552018890",
      "phone_is_mobile": true,
      "addresses": [],
      "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}
}

5. When something goes wrong#

Errors are JSON with a stable code. A request without a key returns 401:

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "A valid API key is required.",
  "code": "api_key_missing",
  "request_id": "6f1c1f0e-5b1d-4c35-9a59-2f1a0b7c9c11",
  "message": "A valid API key is required."
}

Branch on code, and give request_id to support if you contact them. The full list is in Errors, limits and retries.

Next#

• API reference for every endpoint.
• Authentication and API keys for abilities and key replacement.
• Inbound webhooks if the other system can only send data to a URL.