ContactZapp

Creates a contact. It is treated like a contact that arrives from a sync. The contact is written to one of the user's two-way accounts, which ContactZapp chooses: the earliest-linked account that keeps an address book and is not paused. The sync then copies it to every other two-way account, and never to a read-only one. It is matched like any incoming contact: - when the user's auto-merge level covers the match, the values are added to the contact the user already has (200, `merged`); - otherwise the contact is created (201, `created`), and a possible match waits in Review duplicates (201, `needs_review`). A create is never refused for the plan's contact limit. Over the limit, the contact is created frozen (201), and `contact.frozen` in the answer is true. ContactZapp keeps a frozen contact but does not sync it until the user upgrades or frees a place. Send an `Idempotency-Key` header to make a retry safe. A repeat with the same key and the same body within 24 hours answers with the first result and writes nothing. The same key with a different body is a 422.

Subscribes a URL to one event. Zapier, Make and n8n call this when an automation is switched on. The URL must use HTTPS and reach a public address. The answer is 201 with the subscription and its signing `secret`, which is shown only here. Needs the `webhooks:manage` and `contacts:read` scopes. A user can have up to 25 subscriptions. Each event is sent to the URL as a POST with a JSON body. The body is one item, exactly as the polling trigger for the same event lists it. Every delivery has these headers: - `ContactZapp-Signature`: `t=<unix seconds>,v1=<signature>`, where the signature is the hex HMAC-SHA256 of the timestamp, a full stop and the raw body, keyed with the secret. Check it, and refuse a timestamp more than five minutes from your clock. - `ContactZapp-Delivery`: the delivery's id. A retry sends the same id. - `ContactZapp-Event`: the event, for example `contact.created`. Answer with any 2xx status. An answer of 410 removes the subscription. Any other answer, or none within 10 seconds, is retried with backoff for about a day; after the last attempt the subscription is turned off. Each event is sent at least once: deduplicate by the item's `id`.

Starts a sync, the same as pressing Sync now in ContactZapp. The run shows in History as a manual run. The answer is 202 with the state of the sync: `queued` or `running`. If a sync is already going, you get that one back and no second one starts. Needs the `sync:trigger` scope.

Changes a contact's fields, as the app's edit does. Only the fields in the body change; a field the body leaves out keeps its value. The change is recorded in History as the user's, naming the API key, and written to every two-way account the contact is in, never to a read-only one. A contact waiting in Review duplicates cannot be changed until the review is decided (409, `contact_pending_review`). `Idempotency-Key` works as it does when you create a contact.

Returns one contact. `id` is the contact's `id` or its `publicId` (`CS-0042`). A deleted or merged contact is a 404, and so is another user's contact.

Checks an API key. Returns the user the key acts for, the user's plan and the key's scopes. Any live key may call it, so it is the call to make when you want to test a key. Send the key in every request as `Authorization: Bearer <key>`. Each operation names the scope it needs; a key without that scope gets 403. There is a limit on requests; past it the answer is 429 with a `Retry-After` header. Every error body has a stable `code`.

Lists the user's linked accounts, as the Settings screen does: provider, name, sync direction, connection state and when each account last synced.

Finds the user's contacts, or lists them. Give at most one of `email`, `phone` and `query`: - `email` and `phone` find the contacts that hold that address or number. An email is compared ignoring case, and a phone number ignoring formatting. - `query` is the same free-text search the Contacts screen has. - With none of them, every contact is listed, newest first. Pages work with a cursor: pass `nextCursor` back as `cursor`, with the same filter, until a page comes back without one. Deleted and merged contacts are never returned.

Polling trigger: returns the newest events of one type first. This is what Zapier, Make and n8n poll to start an automation. Each item has an `id` that never changes. Polling again with nothing new returns the same ids, and a new event appears at the top. Deduplicate by `id`. `contact.created`, `contact.updated`, `contacts.merged` and `account.needs_attention` come from the change history ContactZapp records. One item is one recorded event, and it is kept as long as the History screen keeps it. `match.needs_review` comes from the duplicate flags the Contacts screen shows: one item for each contact flagged as a possible duplicate and not yet merged. Its `id` changes when the flag is raised again. Each item carries what an automation needs without a second call: the contact's fields (null when the contact has since been deleted or merged), for a merge the ids of the contacts it absorbed, and for an account the account and why it needs attention.

Lists the webhook subscriptions of this API key's user, oldest first: the URL, the event and whether it is `active` or `disabled`. The signing secret is never shown again after the subscription is made. Needs the `webhooks:manage` scope.