{
  "openapi": "3.1.0",
  "info": {
    "title": "ContactZapp API",
    "version": "2.2.0",
    "description": "The ContactZapp API reads and writes the contacts in a ContactZapp account. Use it from Zapier, Make, n8n or your own code.\n\nCreate an API key in ContactZapp under Settings › Advanced. Send it with every request as `Authorization: Bearer <key>`. Start with `GET /api/v1/me` to check the key.\n\nEach operation names the scope it needs. A request whose key or connected app lacks that scope gets 403. Past the request limit, the answer is 429 with a `Retry-After` header. Every error body has a stable `code`.\n\nThis document's version follows semantic versioning. A change that can break a client that worked before (an operation, parameter, field, response or enum value removed; a parameter or field made required; a type narrowed) raises the major number. An addition (an operation, an optional parameter or field, a response, an enum value) raises the minor number. Any other change, wording included, raises the patch number.\n"
  },
  "servers": [
    {
      "url": "https://app.contactz.app"
    }
  ],
  "tags": [
    {
      "name": "API key",
      "description": "Check the API key or access token you send."
    },
    {
      "name": "Contacts",
      "description": "Find, create, read and change the user's contacts."
    },
    {
      "name": "Events",
      "description": "New, changed and merged contacts, possible duplicates and accounts that need attention. Poll them to start an automation.\n"
    },
    {
      "name": "Webhooks",
      "description": "Have events sent to your URL as they happen, instead of polling."
    },
    {
      "name": "Sync",
      "description": "Start a sync now, instead of waiting for the next one."
    }
  ],
  "paths": {
    "/api/v1/me": {
      "get": {
        "operationId": "getV1Me",
        "tags": [
          "API key"
        ],
        "summary": "API key – Check",
        "description": "Returns the user the request acts for, the user's plan, the user's sign-in email and the scopes of the API key or connected app that made it. Any live key or access token can call it, so call it to test one.\n",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "The user the request acts for, with the user's plan, the user's sign-in email and the scopes of the key or connected app.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1Me"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/V1Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/V1RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/V1InternalError"
          },
          "503": {
            "$ref": "#/components/responses/V1Unavailable"
          }
        }
      }
    },
    "/api/v1/contacts": {
      "get": {
        "operationId": "listV1Contacts",
        "tags": [
          "Contacts"
        ],
        "summary": "Contact – Find",
        "description": "Finds the user's contacts by email address, phone number or text. Give at most one of `email`, `phone` and `query`:\n\n- `email` finds the contacts with that address. Case does not matter.\n- `phone` finds the contacts with that number, however it is formatted.\n- `query` searches the way the Contacts screen's search does.\n- With none of them, every contact is listed, newest first.\n\nDeleted and merged contacts are never returned. For the next page, send the `nextCursor` you got as `cursor`, with the same filter. The last page has no `nextCursor`.\n",
        "security": [
          {
            "apiKey": [
              "contacts:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "email",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "phone",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "query",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The previous page's `nextCursor`."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200
            },
            "description": "Page size; 50 when omitted."
          }
        ],
        "responses": {
          "200": {
            "description": "One page of contacts.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1ContactPage"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/V1InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/V1Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/V1Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/V1RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/V1InternalError"
          },
          "503": {
            "$ref": "#/components/responses/V1Unavailable"
          }
        }
      },
      "post": {
        "operationId": "createV1Contact",
        "tags": [
          "Contacts"
        ],
        "summary": "Contact – Create",
        "description": "Adds a contact. If the user already has this person, the values may go to that contact instead:\n\n- If the user's Auto-Merge level covers the match, the values are added to the existing contact: 200, `merged`.\n- Otherwise a new contact is created: 201, `created`. If it may be a duplicate, it also waits in Review duplicates: 201, `needs_review`.\n\nContactZapp saves the contact in one two-way account: the first one the user linked that keeps an address book and is not paused. The next sync copies it to the user's other two-way accounts, never to a read-only one.\n\nA create is never refused for the plan's contact limit. Over the limit, the contact is created frozen and `contact.frozen` is true. ContactZapp keeps a frozen contact but does not sync it until the user upgrades or frees a place.\n\nSend an `Idempotency-Key` header to make a retry safe.\n",
        "security": [
          {
            "apiKey": [
              "contacts:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/V1IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V1ContactInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The values were merged into a contact the user has (`merged`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1ContactWriteResult"
                }
              }
            }
          },
          "201": {
            "description": "A new contact (`created`, or `needs_review` with its possible matches).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1ContactWriteResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/V1BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/V1Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/V1Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/V1Conflict"
          },
          "413": {
            "$ref": "#/components/responses/V1BodyTooLarge"
          },
          "422": {
            "$ref": "#/components/responses/V1Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/V1RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/V1InternalError"
          },
          "503": {
            "$ref": "#/components/responses/V1Unavailable"
          }
        }
      }
    },
    "/api/v1/contacts/{id}": {
      "get": {
        "operationId": "getV1Contact",
        "tags": [
          "Contacts"
        ],
        "summary": "Contact – Read",
        "description": "Returns one contact. `id` is the contact's `id` or its `publicId`, such as `CS-0042`. A deleted or merged contact is a 404, and so is another user's contact.\n",
        "security": [
          {
            "apiKey": [
              "contacts:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The contact.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1Contact"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/V1NotFound"
          },
          "401": {
            "$ref": "#/components/responses/V1Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/V1Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/V1RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/V1InternalError"
          },
          "503": {
            "$ref": "#/components/responses/V1Unavailable"
          }
        }
      },
      "patch": {
        "operationId": "updateV1Contact",
        "tags": [
          "Contacts"
        ],
        "summary": "Contact – Change",
        "description": "Changes a contact, as editing it in ContactZapp does. Only the fields you send change. A field you leave out keeps its value.\n\nThe change goes to every two-way account the contact is in, never to a read-only one. History records it as the user's change and names the API key or the connected app that made it.\n\nA contact waiting in Review duplicates cannot be changed until the review is decided: 409, `contact_pending_review`. Send an `Idempotency-Key` header to make a retry safe.\n",
        "security": [
          {
            "apiKey": [
              "contacts:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The contact's `id` or its `publicId` (`CS-0042`).",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/V1IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V1ContactInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The contact as it is now (`updated`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1ContactWriteResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/V1BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/V1Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/V1Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/V1NotFound"
          },
          "409": {
            "$ref": "#/components/responses/V1Conflict"
          },
          "413": {
            "$ref": "#/components/responses/V1BodyTooLarge"
          },
          "422": {
            "$ref": "#/components/responses/V1Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/V1RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/V1InternalError"
          },
          "503": {
            "$ref": "#/components/responses/V1Unavailable"
          }
        }
      }
    },
    "/api/v1/sync": {
      "post": {
        "operationId": "postV1Sync",
        "tags": [
          "Sync"
        ],
        "summary": "Sync – Start",
        "description": "Starts a sync, the same as Sync now in ContactZapp. History shows it as a manual run. The answer is 202 with the sync's state, `queued` or `running`. If a sync is already going, you get that one back and no second one starts.\n",
        "security": [
          {
            "apiKey": [
              "sync:trigger"
            ]
          }
        ],
        "responses": {
          "202": {
            "description": "A sync is queued or running for this user.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SyncJobStatus"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/V1Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/V1Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/V1RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/V1InternalError"
          },
          "503": {
            "$ref": "#/components/responses/V1Unavailable"
          }
        }
      }
    },
    "/api/v1/triggers/{event}": {
      "get": {
        "operationId": "listV1TriggerEvents",
        "tags": [
          "Events"
        ],
        "summary": "Event – List",
        "description": "Lists the events of one type, newest first. Zapier, Make and n8n poll this to start an automation.\n\nEach item's `id` never changes. Poll again and the items you already have come back with the same ids, with new ones on top. Skip the ids you have seen.\n\n- `contact.created`, `contact.updated`, `contacts.merged` and `account.needs_attention` come from History, and are kept as long as History keeps them.\n- `match.needs_review` lists each contact flagged as a possible duplicate and not yet merged. Its `id` changes when the flag is raised again.\n\nEach item carries what an automation needs, with no second call:\n\n- the contact's fields, or null once the contact is deleted or merged\n- for a merge, the ids of the contacts it absorbed\n- for an account, the account and why it needs attention\n",
        "security": [
          {
            "apiKey": [
              "contacts:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "event",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/V1TriggerEvent"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The previous page's `nextCursor`, to read further back."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            },
            "description": "Page size; 50 when omitted."
          }
        ],
        "responses": {
          "200": {
            "description": "One page of events, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1TriggerPage"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/V1InvalidRequest"
          },
          "404": {
            "$ref": "#/components/responses/V1NotFound"
          },
          "401": {
            "$ref": "#/components/responses/V1Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/V1Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/V1RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/V1InternalError"
          },
          "503": {
            "$ref": "#/components/responses/V1Unavailable"
          }
        }
      }
    },
    "/api/v1/webhooks": {
      "get": {
        "operationId": "listV1Webhooks",
        "tags": [
          "Webhooks"
        ],
        "summary": "Webhook – List",
        "description": "Lists the user's webhook subscriptions, oldest first: the URL, the event, and whether it is `active` or `disabled`. The signing secret is not shown again.\n",
        "security": [
          {
            "apiKey": [
              "webhooks:manage"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The subscriptions.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1WebhookList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/V1Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/V1Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/V1RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/V1InternalError"
          },
          "503": {
            "$ref": "#/components/responses/V1Unavailable"
          }
        }
      },
      "post": {
        "operationId": "createV1Webhook",
        "x-contactzapp-webhook-signature": {
          "header": "ContactZapp-Signature",
          "scheme": "v1",
          "format": "t=<unix seconds>,v1=<hex HMAC-SHA256>",
          "toleranceSeconds": 300
        },
        "tags": [
          "Webhooks"
        ],
        "summary": "Webhook – Subscribe",
        "description": "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 API key or connected app also needs `contacts:read`. A user can have up to 25 subscriptions.\n\nThe answer is 201 with the subscription and its signing `secret`. The secret is shown only here.\n\nEach event is sent to the URL as a POST with a JSON body. The body is one item, exactly as the event list returns it. Every delivery has these headers:\n\n- `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.\n- `ContactZapp-Delivery`: the delivery's id. A retry sends the same id.\n- `ContactZapp-Event`: the event, for example `contact.created`.\n\nAnswer 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. An event can arrive more than once: skip an item `id` you have seen.\n",
        "security": [
          {
            "apiKey": [
              "webhooks:manage"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V1WebhookCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The subscription. `secret` is shown here only.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1WebhookCreated"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/V1WebhookRefused"
          },
          "401": {
            "$ref": "#/components/responses/V1Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/V1Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/V1WebhookLimit"
          },
          "413": {
            "$ref": "#/components/responses/V1BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/V1RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/V1InternalError"
          },
          "503": {
            "$ref": "#/components/responses/V1Unavailable"
          }
        }
      }
    },
    "/api/v1/webhooks/{id}": {
      "delete": {
        "operationId": "deleteV1Webhook",
        "tags": [
          "Webhooks"
        ],
        "summary": "Webhook – Unsubscribe",
        "description": "Removes a webhook subscription. Zapier, Make and n8n call this when an automation is switched off. Deliveries still waiting are not sent.\n",
        "security": [
          {
            "apiKey": [
              "webhooks:manage"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "The subscription is removed."
          },
          "401": {
            "$ref": "#/components/responses/V1Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/V1Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/V1NotFound"
          },
          "429": {
            "$ref": "#/components/responses/V1RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/V1InternalError"
          },
          "503": {
            "$ref": "#/components/responses/V1Unavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "A personal API key, or the OAuth access token of an app the user connected. Send it as `Authorization: Bearer <key>`. Create a key in ContactZapp under Settings › Advanced.\n\nA key starts with `cz_live_` and an access token with `cz_oat_`. Both carry the same scopes. Each operation names the one scope it needs. An empty list means any live key or access token.\n"
      }
    },
    "parameters": {
      "V1IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "Any string of 1 to 255 bytes you choose for this write, such as a UUID. Repeat the request with the same key and body within 24 hours, and you get the first result back and nothing is written twice. The same key with a different body is a 422.\n",
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "V1Unauthorized": {
        "description": "No API key (`api_key_missing`; a session cookie alone counts as none), or one that is not a live key: unknown, revoked or malformed (`api_key_invalid`). For an OAuth access token that has expired or whose app was disconnected: `access_token_invalid`.\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/V1Error"
            }
          }
        }
      },
      "V1Forbidden": {
        "description": "The API key or connected app lacks the scope this route needs (`insufficient_scope`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/V1Error"
            }
          }
        }
      },
      "V1RateLimited": {
        "description": "The request was refused (`rate_limited`) for one of two reasons. The user's API keys and connected apps together made 60 requests in the last minute. Or too many requests from one address came with a key or token that is not valid. Retry-After says, in seconds, when the next request would be served.\n",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/V1Error"
            }
          }
        }
      },
      "V1InvalidRequest": {
        "description": "A query parameter this route cannot use (`invalid_parameter`): a `limit` out of range, a `cursor` this route did not issue, or two filters where one is allowed.\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/V1Error"
            }
          }
        }
      },
      "V1NotFound": {
        "description": "Nothing with this id or name belongs to the user (`not_found`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/V1Error"
            }
          }
        }
      },
      "V1InternalError": {
        "description": "The server could not complete the request (`internal_error`). The cause is logged, never returned.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/V1Error"
            }
          }
        }
      },
      "V1Unavailable": {
        "description": "The API key, the access token or the rate limit could not be checked (`unavailable`). Retry.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/V1Error"
            }
          }
        }
      },
      "V1BadRequest": {
        "description": "The body is not a contact (`invalid_body`), carries an impossible date (`invalid_date`) or no value at all (`empty_contact`), or the Idempotency-Key header is empty or too long (`idempotency_key_invalid`), or the body carries a field a contact write does not take (`unknown_field`).\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/V1Error"
            }
          }
        }
      },
      "V1WebhookRefused": {
        "description": "The body is not a subscription (`invalid_body`), or its URL is not HTTPS, carries a user name, is too long or reaches a private, loopback or link-local address (`invalid_webhook_url`).\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/V1Error"
            }
          }
        }
      },
      "V1WebhookLimit": {
        "description": "The user already has the most webhook subscriptions allowed (`webhook_limit_reached`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/V1Error"
            }
          }
        }
      },
      "V1BodyTooLarge": {
        "description": "The request body is larger than the API accepts (`body_too_large`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/V1Error"
            }
          }
        }
      },
      "V1Conflict": {
        "description": "The contact waits in Review duplicates (`contact_pending_review`), was merged or deleted (`contact_gone`), or changed while it was being written (`contact_changed`, try again). Or a request with this `Idempotency-Key` is still being handled (`idempotency_key_in_progress`).\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/V1Error"
            }
          }
        }
      },
      "V1Unprocessable": {
        "description": "The user has no two-way account that keeps an address book and is not paused (`no_account_to_write_to`), or this Idempotency-Key was used with another body in the last 24 hours (`idempotency_key_reused`).\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/V1Error"
            }
          }
        }
      }
    },
    "schemas": {
      "PartialDate": {
        "type": "object",
        "required": [
          "year",
          "month",
          "day"
        ],
        "additionalProperties": false,
        "description": "A calendar date, any part of which may be missing. A part that is missing is `0`. A birthday with no year is `{\"year\": 0, \"month\": 3, \"day\": 15}`.\n\nNever fill in a missing year yourself: check whether the date has one, and do not show `0` as a year. The API never sends `0` to mean year zero. A date has no time and no time zone.\n",
        "properties": {
          "year": {
            "type": "integer",
            "description": "The Gregorian year, or `0` when the date states none."
          },
          "month": {
            "type": "integer",
            "description": "1-12, or `0` when the date states none."
          },
          "day": {
            "type": "integer",
            "description": "1-31, or `0` when the date states none."
          }
        }
      },
      "LabeledValue": {
        "type": "object",
        "required": [
          "label",
          "value"
        ],
        "additionalProperties": false,
        "description": "One value with its label, such as a phone number labelled \"Mobile\". The label is the one the account gave the value, or an empty string when it has none.\n",
        "properties": {
          "label": {
            "type": "string"
          },
          "value": {
            "type": "string"
          },
          "preferred": {
            "type": "boolean",
            "description": "Marks the preferred entry of its field: the phone number to call, the address to write to. Missing or false means nothing has said so; it does not mean the entry is explicitly not preferred. If your tool does not model preference, leave it out of every entry, so you do not clear the user's choice. Not every provider stores it, so do not expect it to carry over everywhere.\n"
          }
        }
      },
      "AccountProvider": {
        "type": "string",
        "enum": [
          "google",
          "microsoft",
          "apple",
          "carddav"
        ],
        "description": "The provider of a linked account: `google`, `microsoft`, `apple` (iCloud) or `carddav`.\n"
      },
      "AccountDisplayStatus": {
        "type": "string",
        "enum": [
          "never_synced",
          "synced",
          "error",
          "reauthorize",
          "unlinked",
          "user_paused",
          "plan_paused",
          "ok",
          "slowed_down"
        ],
        "description": "How well one linked account is connected.\n\n- `never_synced`: the account is linked and has not synced yet.\n- `synced`: the last sync worked.\n- `error`: the last sync failed.\n- `reauthorize`: the user has to sign in to the account again in ContactZapp.\n- `unlinked`: the account was unlinked.\n- `user_paused`: the user paused the account.\n- `plan_paused`: the account is paused because the user's plan does not cover it. A plan change lifts it.\n- `ok`: connected and healthy. `synced` is what a healthy account reads as today.\n- `slowed_down`: the last sync stopped because the provider asked ContactZapp to slow down or was briefly unavailable. ContactZapp retries by itself; the next good sync clears it.\n"
      },
      "SyncDirection": {
        "type": "string",
        "enum": [
          "bidirectional",
          "read_only"
        ],
        "description": "How changes flow for one linked account. `bidirectional` is two-way sync. `read_only` accounts are read from and never written to.\n"
      },
      "ApiKeyScope": {
        "type": "string",
        "description": "One permission an API key or a connected app carries:\n\n- `contacts:read` reads contacts and events.\n- `contacts:write` creates and changes contacts.\n- `sync:trigger` starts a sync.\n- `webhooks:manage` subscribes and unsubscribes webhooks.\n",
        "enum": [
          "contacts:read",
          "contacts:write",
          "sync:trigger",
          "webhooks:manage"
        ]
      },
      "V1Me": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "userId",
          "plan",
          "scopes"
        ],
        "properties": {
          "userId": {
            "type": "string"
          },
          "plan": {
            "type": "string",
            "description": "The name of the user's plan, as ContactZapp shows it. Any string: new plans can appear.\n"
          },
          "email": {
            "type": "string",
            "description": "The account's sign-in email, so a connection can be told apart by it.\n"
          },
          "scopes": {
            "type": "array",
            "description": "The scopes of the API key or connected app that made this request.",
            "items": {
              "$ref": "#/components/schemas/ApiKeyScope"
            }
          }
        }
      },
      "V1ContactFields": {
        "type": "object",
        "description": "The contact fields a read shows and a write can change. A write takes exactly these names, in the same shapes a read returns them.\n",
        "properties": {
          "firstName": {
            "type": "string"
          },
          "middleName": {
            "type": "string"
          },
          "lastName": {
            "type": "string"
          },
          "prefix": {
            "type": "string"
          },
          "suffix": {
            "type": "string"
          },
          "nickname": {
            "type": "string"
          },
          "organization": {
            "type": "string"
          },
          "jobTitle": {
            "type": "string"
          },
          "emails": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LabeledValue"
            }
          },
          "phones": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LabeledValue"
            }
          },
          "addresses": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LabeledValue"
            }
          },
          "urls": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LabeledValue"
            }
          },
          "birthday": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PartialDate"
              },
              {
                "type": "null"
              }
            ],
            "description": "Null when the contact has none. In a write, null clears the stored birthday, and so does a date whose year, month and day are all `0`; an absent field keeps it.\n"
          },
          "notes": {
            "type": "string"
          },
          "labels": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "V1Contact": {
        "description": "One contact, as the public API shows it: the vCard-shaped fields an automation reads, under names that do not change. An absent value is an empty string or list. `id`, `publicId`, `displayName`, `updatedAt` and `frozen` are read-only; every other field can be changed by a write.\n",
        "allOf": [
          {
            "$ref": "#/components/schemas/V1ContactFields"
          },
          {
            "type": "object",
            "required": [
              "id",
              "publicId",
              "displayName",
              "firstName",
              "middleName",
              "lastName",
              "prefix",
              "suffix",
              "nickname",
              "organization",
              "jobTitle",
              "emails",
              "phones",
              "addresses",
              "urls",
              "birthday",
              "notes",
              "labels",
              "updatedAt",
              "frozen"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "The contact's stable id."
              },
              "publicId": {
                "type": "string",
                "description": "The id the app shows (`CS-0042`); empty for a contact the app has not numbered yet."
              },
              "displayName": {
                "type": "string",
                "description": "The name the app shows for the contact."
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "description": "When the contact last changed."
              },
              "frozen": {
                "type": "boolean",
                "description": "True when the user's plan freezes this contact: ContactZapp keeps it but does not sync it to their accounts until they upgrade or free a place under the plan's contact limit. A create over the limit still answers 201 and returns the new contact with `frozen` true.\n"
              }
            }
          }
        ]
      },
      "V1ContactPage": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contacts"
        ],
        "properties": {
          "contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V1Contact"
            }
          },
          "nextCursor": {
            "type": "string",
            "description": "Present when another page follows; pass it back as `cursor`."
          }
        }
      },
      "V1Account": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "provider",
          "name",
          "direction",
          "status",
          "lastSyncAt"
        ],
        "description": "One linked account.",
        "properties": {
          "id": {
            "type": "string"
          },
          "provider": {
            "$ref": "#/components/schemas/AccountProvider"
          },
          "name": {
            "type": "string"
          },
          "direction": {
            "$ref": "#/components/schemas/SyncDirection"
          },
          "status": {
            "$ref": "#/components/schemas/AccountDisplayStatus"
          },
          "lastSyncAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the account last synced; null if it never has."
          }
        }
      },
      "V1TriggerEvent": {
        "type": "string",
        "description": "The events the API reports, as polling triggers.\n\n- `contact.created`: a contact was added.\n- `contact.updated`: a contact was changed.\n- `contacts.merged`: contacts were merged into one.\n- `match.needs_review`: a contact is flagged as a possible duplicate and waits in Review duplicates.\n- `account.needs_attention`: a linked account needs the user to look at it.\n",
        "enum": [
          "contact.created",
          "contact.updated",
          "contacts.merged",
          "match.needs_review",
          "account.needs_attention"
        ]
      },
      "V1AccountAttention": {
        "type": "string",
        "description": "Why an account needs attention.\n\n- `sync_failed`: reading the account failed, and the user has to look at it. A temporary slowdown or outage at the provider, which ContactZapp retries by itself, is not reported.\n- `reconnect_needed`: the account's sign-in no longer works, and syncs skip it until the user signs in again.\n- `paused_over_plan_limit`: a sync skipped the account because the user's plan paused it.\n- `disconnected_after_pause`: the account stayed paused for too long and was disconnected.\n",
        "enum": [
          "sync_failed",
          "reconnect_needed",
          "paused_over_plan_limit",
          "disconnected_after_pause"
        ]
      },
      "V1TriggerItem": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "event",
          "occurredAt"
        ],
        "description": "One event. The fields it carries depend on `event`:\n\n- a contact event: `contactId` and `contact`\n- a merge: also `absorbedContactIds` and `automatic`\n- a possible duplicate: `contactId`, `contact`, `pairedContactId`, `pairedContact` and `confidence`\n- an account event: `accountId`, `account` and `attention`\n",
        "properties": {
          "id": {
            "type": "string",
            "description": "The event's stable id. Deduplicate by it."
          },
          "event": {
            "$ref": "#/components/schemas/V1TriggerEvent"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          },
          "contactId": {
            "type": "string",
            "description": "The contact the event is about; for a merge, the contact that survived."
          },
          "contact": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/V1Contact"
              },
              {
                "type": "null"
              }
            ],
            "description": "The contact as it is now; null when it has since been deleted or merged."
          },
          "absorbedContactIds": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The ids of the contacts merged into `contactId`."
          },
          "automatic": {
            "type": "boolean",
            "description": "The merge was made by auto-merge rather than by the user."
          },
          "pairedContactId": {
            "type": "string",
            "description": "For a review, the other contact of the pair."
          },
          "pairedContact": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/V1Contact"
              },
              {
                "type": "null"
              }
            ],
            "description": "For a review, the other contact of the pair as it is now."
          },
          "confidence": {
            "type": "integer",
            "description": "How sure the matcher is that the two contacts are the same person, 0-100."
          },
          "accountId": {
            "type": "string",
            "description": "The account the event is about; absent when the account has since been removed."
          },
          "account": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/V1Account"
              },
              {
                "type": "null"
              }
            ],
            "description": "The account as it is now; null when it has since been removed."
          },
          "attention": {
            "$ref": "#/components/schemas/V1AccountAttention"
          }
        }
      },
      "V1TriggerPage": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V1TriggerItem"
            }
          },
          "nextCursor": {
            "type": "string",
            "description": "Present when older events follow; pass it back as `cursor`."
          }
        }
      },
      "WebhookState": {
        "type": "string",
        "description": "A webhook subscription's state. `active`: events are sent to it. `disabled`: it was turned off after its deliveries failed for about a day.\n",
        "enum": [
          "active",
          "disabled"
        ]
      },
      "V1WebhookCreateRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "url",
          "event"
        ],
        "properties": {
          "url": {
            "type": "string",
            "maxLength": 2048,
            "description": "The HTTPS URL to deliver to."
          },
          "event": {
            "$ref": "#/components/schemas/V1TriggerEvent"
          }
        }
      },
      "V1Webhook": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "url",
          "event",
          "state",
          "createdAt",
          "disabledAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The subscription's id; unsubscribe with it."
          },
          "url": {
            "type": "string"
          },
          "event": {
            "$ref": "#/components/schemas/V1TriggerEvent"
          },
          "state": {
            "$ref": "#/components/schemas/WebhookState"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "disabledAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the subscription was turned off; null while active."
          }
        }
      },
      "V1WebhookCreated": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "webhook",
          "secret"
        ],
        "description": "A new subscription, with its signing secret, shown once.",
        "properties": {
          "webhook": {
            "$ref": "#/components/schemas/V1Webhook"
          },
          "id": {
            "type": "string",
            "description": "The subscription's id again, at the top level, where REST-hook clients read it."
          },
          "secret": {
            "type": "string",
            "description": "The signing secret (`cz_whsec_` and 43 characters). Shown here only."
          }
        }
      },
      "V1WebhookList": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "webhooks"
        ],
        "properties": {
          "webhooks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V1Webhook"
            }
          }
        }
      },
      "V1ContactInput": {
        "description": "The body of a contact create or update: the contact fields a read shows that a write can change, under the same names and in the same shapes, and nothing else.\n\nA field the body carries that is not one of them is refused with a 400 `unknown_field`, and nothing is written. That includes the read-only `id`, `publicId`, `displayName` and `updatedAt`, so writing back a whole contact as a read returned it answers 400 `unknown_field`: send only the fields you change.\n\nA create writes the fields the body carries. An update is change-only: a field the body does not carry keeps its value, a field it carries empty (`\"\"`, `[]`, or a date whose year, month and day are all `0`) is cleared, and a list it carries replaces the stored list. `\"birthday\": null` clears the birthday too, and a birthday the body does not carry is kept. Fields ContactZapp keeps that a read does not show are never changed by an update.\n",
        "allOf": [
          {
            "$ref": "#/components/schemas/V1ContactFields"
          }
        ]
      },
      "V1ContactWriteOutcome": {
        "type": "string",
        "enum": [
          "created",
          "merged",
          "needs_review",
          "updated"
        ],
        "description": "What a contact write did:\n\n- `created`: a new contact that matched none the user has.\n- `merged`: the contact matched one the user has, and the user's Auto-Merge level covers the match. The values were added to that contact, and nothing was created.\n- `needs_review`: a new contact that may be a duplicate of one the user has. The pair waits in Review duplicates.\n- `updated`: an existing contact was changed.\n"
      },
      "V1ContactMatch": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contact",
          "confidence"
        ],
        "description": "A contact the user has that a created contact matched, and the matcher's score for the pair.\n",
        "properties": {
          "contact": {
            "$ref": "#/components/schemas/V1Contact"
          },
          "confidence": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "The matcher's score for the pair, 0-100."
          }
        }
      },
      "V1ContactWriteResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "outcome",
          "contact"
        ],
        "description": "The answer of a contact write. `contact` is the contact written (the new one, the one merged into, or the one updated), as every read shows it (V1Contact). `possibleMatches` is present only for `needs_review`.\n",
        "properties": {
          "outcome": {
            "$ref": "#/components/schemas/V1ContactWriteOutcome"
          },
          "contact": {
            "$ref": "#/components/schemas/V1Contact"
          },
          "possibleMatches": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/V1ContactMatch"
            }
          }
        }
      },
      "V1ErrorCode": {
        "type": "string",
        "description": "The stable, machine-readable reason of an error. Show `message` to the person building the automation, and branch on `code`.\n\n- `api_key_missing`: the request has no API key.\n- `api_key_invalid`: the API key is not valid. It may have been revoked.\n- `access_token_invalid`: the OAuth access token is not valid: it has expired, or the app was disconnected. Refresh it, or connect again.\n- `insufficient_scope`: the API key or connected app does not have the scope this operation needs.\n- `rate_limited`: too many requests. Wait the number of seconds in the `Retry-After` header.\n- `internal_error`: something went wrong in ContactZapp. Try again.\n- `unavailable`: ContactZapp could not check the request just now. Try again.\n- `invalid_parameter`: a parameter is not usable, for example a limit out of range, a cursor from another request, or more than one filter.\n- `not_found`: there is nothing at this address for this account.\n- `invalid_body`: the request body is not a contact.\n- `invalid_date`: a date in the request is not a real date.\n- `empty_contact`: the contact has no values.\n- `no_account_to_write_to`: the user has no two-way account that keeps an address book and is not paused.\n- `contact_gone`: the contact was merged into another contact or deleted.\n- `contact_pending_review`: the contact waits in Review duplicates.\n- `contact_changed`: the contact changed while it was being written. Try again.\n- `idempotency_key_invalid`: the `Idempotency-Key` header is empty, too long or has more than one value.\n- `idempotency_key_reused`: this `Idempotency-Key` was already used with a different request.\n- `idempotency_key_in_progress`: a request with this `Idempotency-Key` is still being handled, or did not finish.\n- `body_too_large`: the request body is too large.\n- `unknown_field`: the body carries a field a contact write does not take: a misspelt name, a read-only field such as `id` or `updatedAt`, or a field the contact does not show. Nothing was written.\n- `invalid_webhook_url`: the webhook URL does not use HTTPS, carries a user name, is too long, or reaches a private address.\n- `webhook_limit_reached`: the user already has the most webhook subscriptions allowed.\n",
        "enum": [
          "api_key_missing",
          "api_key_invalid",
          "access_token_invalid",
          "insufficient_scope",
          "rate_limited",
          "internal_error",
          "unavailable",
          "invalid_parameter",
          "not_found",
          "invalid_body",
          "invalid_date",
          "empty_contact",
          "no_account_to_write_to",
          "contact_gone",
          "contact_pending_review",
          "contact_changed",
          "idempotency_key_invalid",
          "idempotency_key_reused",
          "idempotency_key_in_progress",
          "body_too_large",
          "unknown_field",
          "invalid_webhook_url",
          "webhook_limit_reached"
        ]
      },
      "V1Error": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "$ref": "#/components/schemas/V1ErrorCode"
          },
          "message": {
            "type": "string",
            "description": "A sentence for a person, in English."
          }
        }
      },
      "SyncJobStatus": {
        "type": "object",
        "required": [
          "status"
        ],
        "additionalProperties": false,
        "description": "The state of the sync after you asked it to start. It is not a record of a run: it has no id.\n",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "cancelling",
              "idle"
            ],
            "description": "`queued` when your call started a sync; `running` when a sync was already going and your call started nothing.\n"
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the sync that was already going began. Absent for a sync your call just started."
          }
        }
      }
    }
  }
}
