ContactZappStart Free
Guides

Getting started

Create an API key, check that it works, then add your first contact.

  1. Create a key. In ContactZapp, open Settings, then Advanced. Under API keys, choose Create key. Name it after the tool that will use it, and tick what it can do: “Read your contacts”, “Add and change contacts”, or both. Copy the key when it appears. We won’t show it again.
  2. Keep it in a variable. The examples below read the key from CZ_KEY, so it never sits in a command you paste into a chat or a ticket.
    export CZ_KEY='paste your key here'
  3. Check the key. GET /api/v1/me works for any live key. It says who the key acts for, the plan and the scopes.
    Request
    curl -s https://app.contactz.app/api/v1/me \
  -H "Authorization: Bearer $CZ_KEY"
    Answer, 200
    {
  "userId": "99831e44-834d-4405-b7d6-08478451ae4d",
  "plan": "unlimited",
  "scopes": ["contacts:read", "contacts:write"]
}
    A 401 means the key is missing or not valid. See Errors.
  4. Add a contact. This needs the “Add and change contacts” scope.
    Request
    curl -s -X POST https://app.contactz.app/api/v1/contacts \
  -H "Authorization: Bearer $CZ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-call-1" \
  -d '{
    "firstName": "Ada",
    "lastName": "Lovelace",
    "organization": "Analytical Engines",
    "emails": [{ "label": "work", "value": "[email protected]" }],
    "phones": [{ "label": "mobile", "value": "+44 20 7946 0123" }]
  }'
    Answer, 201
    {
  "outcome": "created",
  "contact": {
    "id": "772189b9-ef30-44a8-ace6-3955d061633c",
    "publicId": "CS-0902",
    "displayName": "Ada Lovelace",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "organization": "Analytical Engines",
    "emails": [{ "label": "work", "value": "[email protected]" }],
    "phones": [{ "label": "mobile", "value": "+44 20 7946 0123" }],
    "birthday": null,
    "frozen": false,
    "updatedAt": "2026-11-01T14:47:15.389252Z"
    // …and the other contact fields, empty
  }
}
    The contact is saved in one of your two-way accounts, and ContactZapp sends it to your other two-way accounts. How a created contact is matched and synced says how.
  5. Find it again. This needs the “Read your contacts” scope.
    Request
    curl -s "https://app.contactz.app/api/v1/[email protected]" \
  -H "Authorization: Bearer $CZ_KEY"
    The answer is { "contacts": [ … ] }. It lists the contacts that hold that address.

Next