> ## 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.

# Create contact

> Create a new contact in a Nedzo workspace via the REST API. Provide a phone number, name, email, tags, and custom field values to add a contact record.

<Tip>
  `workspaceId` is required for **account-scoped** API keys and inferred from the key for **workspace-scoped** keys. See [Workspace ID and Request Scope](/authentication#workspace-id-and-request-scope).
</Tip>

<ParamField body="workspaceId" type="string">
  Workspace UUID (required for account API keys, optional for workspace API keys)
</ParamField>

<ParamField body="firstName" type="string">
  First name
</ParamField>

<ParamField body="lastName" type="string">
  Last name
</ParamField>

<ParamField body="email" type="string">
  Email address
</ParamField>

<ParamField body="phone" type="string">
  Phone number (E.164 format)
</ParamField>

<ParamField body="timezone" type="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`.
</ParamField>

<ParamField body="tags" type="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.
</ParamField>

<ParamField body="customFields" type="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.
</ParamField>

<Note>
  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.
</Note>

<Note>
  `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`](/api-reference/contacts/upsert) instead if you want create-or-update semantics.

  ```json 409 Conflict theme={null}
  {
    "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." }
    ]
  }
  ```
</Note>

<RequestExample>
  ```bash cURL theme={null}
  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
        }
      }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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"
  }
  ```
</ResponseExample>