Skip to main content
POST
/
contacts
curl -X POST "https://api.nedzo.ai/v1/contacts" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com",
      "phone": "+14155551234",
      "timezone": "America/Los_Angeles",
      "tags": ["newsletter", "vip"],
      "customFields": {
        "Lead Source": "Website",
        "MRR": 250
      }
    }'

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspaceId": "789e4567-e89b-12d3-a456-426614174000",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "phone": "+14155551234",
  "timezone": "America/Los_Angeles",
  "tags": ["newsletter", "vip"],
  "customFields": {
    "Lead Source": "Website",
    "MRR": "250"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.nedzo.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
workspaceId
string
Workspace UUID (required for account API keys, optional for workspace API keys)
​
firstName
string
First name
​
lastName
string
Last name
​
email
string
Email address
​
phone
string
Phone number (E.164 format)
​
timezone
string
IANA timezone identifier (e.g. America/New_York, Europe/Amsterdam). Used by features that respect the contact’s local time, such as workflow scheduling and campaign send windows.
  • Optional. When omitted, the timezone is auto-derived from the phone number (US area code or country code). If the phone can’t be resolved to a region, the workspace’s default timezone is used as fallback. If neither resolves, the field is left null.
  • Caller-supplied values always win — if you pass a value, it’s stored as-is.
  • Must be a valid IANA timezone identifier; bogus strings are rejected with 400 Bad Request.
​
tags
string[]
Tag names to attach to the contact. Tags that don’t exist yet in your workspace are auto-created. Tag attachment is additive — this endpoint never removes a tag from a contact.
  • Names are matched case-sensitively ("VIP" and "vip" are different tags), trimmed of leading/trailing whitespace, and must be 1–255 characters.
  • Pass an empty array ([]) to no-op (no tags attached, none removed).
  • Tags in the response are returned in alphabetical order regardless of input order.
​
customFields
object
Custom field values keyed by the custom variable name as displayed in the dashboard (e.g. "Lead Source" — including spaces and original casing; not a slug). Unknown keys are rejected with a 400. Define new custom variables on the Contacts page before referencing them via the API.
  • Accepts string, number, boolean, or null. All values are persisted as text and returned as strings regardless of input type (e.g. 250 → "250").
  • Pass null to clear a stored value.
This endpoint strictly validates the request body. Unknown top-level fields are rejected with a 400 Bad Request. Custom field values must use the customFields object — they cannot be added as top-level fields.
curl -X POST "https://api.nedzo.ai/v1/contacts" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com",
      "phone": "+14155551234",
      "timezone": "America/Los_Angeles",
      "tags": ["newsletter", "vip"],
      "customFields": {
        "Lead Source": "Website",
        "MRR": 250
      }
    }'

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspaceId": "789e4567-e89b-12d3-a456-426614174000",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "phone": "+14155551234",
  "timezone": "America/Los_Angeles",
  "tags": ["newsletter", "vip"],
  "customFields": {
    "Lead Source": "Website",
    "MRR": "250"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}