# Quickstart

> Create an API key, make your first request and read the response, in about five minutes.

- Canonical URL: https://couplrfsm.com/developers/quickstart
- Markdown: https://couplrfsm.com/developers/quickstart.md
- API version: v1 (base URL https://couplrfsm.com/api/v1)
- OpenAPI specification: https://couplrfsm.com/developers/openapi.yaml
- All documentation pages: https://couplrfsm.com/llms.txt

> **Flip:** This is the fastest way in. Five steps, about five minutes, and you'll have created a real customer through the API. Every command below can be copied as is; swap in your own key where you see `YOUR_API_KEY`.

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.

> **Flip:** I only show a key once, and I can't look it up for you later. If you lose it, make a new one and revoke the old one.

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.

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

Response (`200`):

```json
{
  "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

```bash
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`):

```json
{
  "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"
  }
}
```

> **Flip:** A few things I do with what you send, so nothing surprises you:

- 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](https://couplrfsm.com/developers/errors-and-limits#idempotency).
- Creating a customer through the API does not email the customer unless you send `"send_card_request": true`.

## 4. Read it back

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

Response (`200`):

```json
{
  "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`:

```json
{
  "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."
}
```

> **Flip:** Read the `code`, not the sentence. I may reword a message, but I won't change a code.

Branch on `code`, and give `request_id` to support if you contact them. The full list is in [Errors, limits and retries](https://couplrfsm.com/developers/errors-and-limits#error-codes).

## Next

- [API reference](https://couplrfsm.com/developers/api-reference) for every endpoint.
- [Authentication and API keys](https://couplrfsm.com/developers/authentication) for abilities and key replacement.
- [Inbound webhooks](https://couplrfsm.com/developers/inbound-webhooks) if the other system can only send data to a URL.