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 '{
      "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
      }
    }'

{
  "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"
}
workspaceId is required for account-scoped API keys and inferred from the key for workspace-scoped keys. See Workspace ID and Request Scope.
​
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.
phone and email are unique per workspace among non-deleted contacts. If another active contact in the same workspace already has the same phone or email, the request fails with 409 Conflict and an errors array indicating which field collided. Use POST /contacts/upsert instead if you want create-or-update semantics.
409 Conflict
{
  "type": "https://api.nedzo.ai/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A contact with this phone already exists in this workspace.",
  "instance": "/v1/contacts",
  "errors": [
    { "field": "phone", "message": "A contact with this phone already exists in this workspace." }
  ]
}

curl -X POST "https://api.nedzo.ai/v1/contacts" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "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
      }
    }'

{
  "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"
}