# Contacts and conversations over the API

> The SkedX Flow API reads and updates contacts and conversations with an API key (header Authorization: Bearer <key>). GET https://flowserver.skode.ai/api/v1/contacts/ (permission contacts:read) takes search (name, email or phone contains), email, phone, limit (up to 200, default 50) and offset, and returns {contacts, total, limit, offset}. POST /api/v1/contacts/ (contacts:write) creates one from a phone with its country code, or an email — 409 with the existing id if that number or email is already a contact. PATCH /api/v1/contacts/ takes the contact’s id plus the fields to change. GET /api/v1/conversations/ (conversations:read) takes channel, status, limit and offset; each conversation carries replyability — whether you can reply with free text now (canFreeReply), hours left in the window and why not. PATCH /api/v1/conversations/ (conversations:write) with id and, for example, status OPEN, PENDING or RESOLVED. A key sees only its own workspace; another workspace’s id returns 404.

Product: SkedX Flow · Topic: APIs & Developers · Draft — steps not yet re-verified in the live product

Your CRM or back office can read what Flow knows about a person and keep it up to date: find a contact by phone or email, add tags, and check a conversation before replying. One key, four requests. About six minutes.

## Step 1: Give the key the right permissions

Reading needs **Read contacts** or **Read conversations**; changing needs **Create and update contacts** or **Update conversations**. Tick only what your system does — [create a key](https://skode.ai/help/flow/developers/create-an-api-key/). A missing permission is named in a `403`.

## Step 2: Find a contact

`GET /api/v1/contacts/` with `search` matches any part of a name, email or phone — the easiest way to find someone by number is to search its digits. Or ask exactly with `email` or `phone`. Each contact comes back with its `id`, name, phone, tags, custom fields and the channel they last used. Up to 50 come back at a time (`limit`, up to 200), newest activity first; page on with `offset`.

```bash
curl -s "https://flowserver.skode.ai/api/v1/contacts/?search=9876543210" \
  -H "Authorization: Bearer $FLOW_API_KEY"
```

## Step 3: Update a contact

Send `PATCH /api/v1/contacts/` with the contact’s `id` and only the fields to change — name, email, company, tags, custom fields. A list such as `tags` is replaced as a whole, so send the full list you want.

```bash
curl -s -X PATCH "https://flowserver.skode.ai/api/v1/contacts/" \
  -H "Authorization: Bearer $FLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "<contact id>", "tags": ["paid", "batch-108"]}'
```

## Step 4: List conversations — and see if you can reply

`GET /api/v1/conversations/` takes `channel` (such as `WHATSAPP`), `status` (`OPEN`, `PENDING` or `RESOLVED`), `limit` and `offset`, newest first. Each conversation carries `replyability`: `canFreeReply` says whether free text is allowed right now, `hoursRemaining` how long the window stays open, and `reason` why not — here, a customer who has never written, so only a template can start the conversation. Check it before a free-text reply; otherwise send a [template](https://skode.ai/help/flow/developers/send-a-whatsapp-template-over-the-api/).

```bash
curl -s "https://flowserver.skode.ai/api/v1/conversations/?channel=WHATSAPP&status=OPEN&limit=20" \
  -H "Authorization: Bearer $FLOW_API_KEY"
```

## Step 5: Change a conversation’s status

Send `PATCH /api/v1/conversations/` with the conversation’s `id` and the new `status` — `OPEN`, `PENDING` or `RESOLVED`. Flow saves what you send as it is, so stick to those values.

```bash
curl -s -X PATCH "https://flowserver.skode.ai/api/v1/conversations/" \
  -H "Authorization: Bearer $FLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "<conversation id>", "status": "RESOLVED"}'
```

## Step 6: Create a contact

Send `POST /api/v1/contacts/` with the person’s number (with its country code) or email, plus anything else you know — name, company, tags. The key needs **Create and update contacts**. Flow stores the number the way it stores every contact, `+` and the country code first, and answers `201` with the new contact and its `id`. If that number — or, without a number, that email — already belongs to a contact, you get `409` with the existing contact’s `id` instead of a duplicate: update that one with `PATCH`. Flow also creates contacts on its own when you [send someone a template](https://skode.ai/help/flow/developers/send-a-whatsapp-template-over-the-api/) or an [inbound hook](https://skode.ai/help/flow/developers/inbound-hooks-send-without-code/) runs **Create or update the contact**.

```bash
curl -s -X POST "https://flowserver.skode.ai/api/v1/contacts/" \
  -H "Authorization: Bearer $FLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Meera Nair", "phone": "+91XXXXXXXXXX", "tags": ["enquiry"]}'
```

## Common questions

### Why do I get 404 for a contact I can see in Flow?

A key only sees its own workspace. If you run several workspaces, use a key made in the one that holds the contact.

### How do I get more than 200 at a time?

You can’t in one request. Page through with `offset`: 0, 200, 400… until you have `total`.

### Can I filter conversations by the agent they’re assigned to?

Yes — add `assignedTo=<agent id>` to `GET /api/v1/conversations/`. An agent’s id is the `assignedTo` value on any conversation they hold.

### Should I send phone numbers with a + here?

For `search`, use the digits alone: it matches any part of the stored number, however it was saved.

## Useful links
- Flow API reference — every field of a contact and a conversation: https://flow.skode.ai/docs/
- API Keys in Flow — add the contacts and conversations permissions: https://flow.skode.ai/settings/api-keys/

Videos and screenshots © 2026 SkedX, with sample data only. Share and link to them freely; copying the SkedX product or its design is not allowed. Terms: https://skode.ai/terms/

## Related guides
- Send a WhatsApp template over the API: https://skode.ai/help/flow/developers/send-a-whatsapp-template-over-the-api/
- Create an API key: https://skode.ai/help/flow/developers/create-an-api-key/
- Flow API errors, and how to fix each one: https://skode.ai/help/flow/developers/flow-api-errors/
- A contact’s Activity in SkedX Flow: everything that happened, in one list: https://skode.ai/help/flow/contacts/a-contacts-activity-in-skode-flow/

Source: https://skode.ai/help/flow/developers/contacts-and-conversations-api/