> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.zorvia.io/connect-api/overview/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.zorvia.io/_mcp/server.

# Connect API overview

> Integrate external systems with Zorvia contacts and messaging.

The Connect API lets external systems manage contacts and send and read messages on behalf of a channel. The authenticated channel is the actor for every request, and all resources are scoped to the workspace identified by the request hostname.

Use the Connect API to:

* create, find, and update contacts;
* list contacts, channels, and channel templates;
* retrieve channel messages;
* send text and template messages, including [encrypted messages](/connect-api/encrypted-messages); and
* close or reopen conversations.

All endpoints are rooted at `/api/connect`. Create a channel API key from **Channel → Settings → API Key**, then send it as a bearer token. See [Authentication](/authentication) before making your first request.

## Update contact information

Use `PATCH /api/connect/contacts/{contact}` to update an existing contact's name, email, or phone. Replace `{contact}` with the UUID returned as `id` when you list, create, or find a contact. A valid Connect token can update any non-deleted contact in its workspace, even when the contact is not linked to the authenticated channel.

Send at least one supported field. Omitted fields stay unchanged:

```http
PATCH /api/connect/contacts/d20f3c70-0269-4ff9-9fd2-08f592f68f10
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json

{
  "name": "Ada Okafor",
  "email": "ada@acme.com",
  "phone": "+2348031234567"
}
```

| Field   | Rules                                                                                                                                                                    |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`  | 2–255 characters after trimming. Cannot be cleared.                                                                                                                      |
| `email` | Valid email, at most 255 characters, unique among other non-deleted contacts in the workspace.                                                                           |
| `phone` | Valid E.164 number with a leading `+` and country code, without spaces or punctuation. Must be unique among other non-deleted contacts, including stored phone variants. |

Strings are trimmed before validation. To clear an email or phone, send `null` or a blank string. When either contact method is supplied, the contact must retain at least one email or phone after the update. For example, this replaces the phone with an email in one request:

```json
{
  "email": "ada@acme.com",
  "phone": null
}
```

Name-only updates are also allowed for legacy contacts that have neither an email nor a phone. Sending the contact's current email or phone is allowed. Unsupported fields are ignored; this endpoint cannot change status, assignments, channel links, or metadata.

A successful request returns `200` with the updated contact under `data.contact`. The response uses `phoneNumber` for the phone field, while the request uses `phone`.

Invalid fields, duplicate contact methods, an empty or unsupported-only body, or clearing the last contact method return `422` with field messages under `errors`. Validation failures apply no changes. A malformed, missing, deleted, or other-workspace contact UUID returns `404`. Unexpected update failures return `500` with `{"status":"error","message":"Internal server error"}` and roll back the changes.

Both channel and connection bearer tokens are supported. When a connection token is linked to multiple active channels, include `X-Channel-Uuid` with the target channel UUID. Missing, invalid, expired, or unavailable credentials return `401`.

## Recipient and attribution semantics

Message requests accept three recipient forms, resolved in this order:

1. `to` — a contact UUID, including a group contact, or an object containing contact details;
2. `contact` — an object containing contact details; or
3. `sender` — the legacy recipient object, used when neither `to` nor `contact` is present.

Use `from` to attribute a message to a Zorvia user or an external actor. When omitted, the authenticated channel is recorded as the sender.

Groups are represented as contacts. Retrieve the group from the contacts endpoint, then use its contact UUID in `to` to send a message directly to the group.

## Send without reopening a conversation

Set `silent` to `true` when sending a message to an existing closed conversation and you want it to remain closed. The message is delivered and recorded on that conversation without creating a reopen state change. Omit `silent`, or set it to `false`, to use the normal conversation behavior.

## JSON requests

Send `Content-Type: application/json` and `Accept: application/json` with request bodies. Collection endpoints support pagination and return pagination metadata alongside their data.

> **Warning**
>
> Connect credentials are privileged. Store them only in a secure backend or secret manager.

> Integrate external systems with Zorvia contacts and messaging.