> ## Documentation Index
> Fetch the complete documentation index at: https://docs.protodesk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Customers and conversations

> Connect your application's customer records to support conversations.

Use customer `externalId` values to connect your application's records with Protodesk. Store the returned Protodesk IDs for subsequent requests.

## Sync a customer

Use `PUT /customers` to upsert by `externalId`. This requires `customers:write`. See [Upsert a customer](/api-reference/customers/upsertCustomer) for the complete schema.

```bash theme={null}
curl --fail-with-body -X PUT 'https://api.protodesk.io/v1/customers' \
  -H "Authorization: Bearer $PROTODESK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"externalId":"customer_123","name":"Alex Example","email":"alex@example.com"}'
```

This request writes to your workspace. Use a dedicated test workspace while developing.

## Open a conversation

Use `POST /conversations` with the returned `customerId`. Include an `externalId` if your system already has a stable ticket or case identifier. The [endpoint reference](/api-reference/conversations/createConversation) describes the subject, channel, routing, and other supported fields.

Use an `Idempotency-Key` for creation requests you may need to retry. Read your workspace's [statuses](/api-reference/statuses-and-priorities/listStatuses) and [priorities](/api-reference/statuses-and-priorities/listPriorities) rather than assuming every workspace uses the same values.

## Associate a channel identity

A customer may have identities for different communication channels. [Link a channel identity](/api-reference/channel-identities/createIdentity) when your workflow needs a specific external address or channel identifier. Do not assume an email field alone establishes every channel connection.

## Add messages and route work

Use the [messages endpoint](/api-reference/messages/createMessage) to add a message. Its public payload uses `externalId`, `sender`, `body`, `channel`, `attachments`, `metadata`, and `internal` where supported by the schema.

<Warning>
  An outbound message can contact a real customer through a configured channel. Confirm the workspace, recipient, and channel before sending. A test-mode API key does not prevent delivery.
</Warning>

Assign conversations with [the assignment endpoint](/api-reference/conversations/assignConversation), and resolve them with [the resolution endpoint](/api-reference/conversations/resolveConversation).

## Keep your system current

Subscribe to [webhooks](/guides/webhooks) for background updates, or use [realtime events](/guides/realtime) for a live server-side stream. Store event IDs so retries do not repeat your side effects.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.