<Intro>

<EndpointHeader />

<Description>

Creates a contact in the workspace. The email address is the contact's identity: it is stored trimmed and lowercased, and creating a second contact with the same email, or reusing another contact's `external_id`, returns a conflict error.

To create or update many contacts in one request, or to write a contact without knowing whether the address already exists, use [Create or update contacts in bulk](/docs/api/reference/create-contact-batch) instead.

</Description>

</Intro>

<Payload kind="request">

<Field name="email" type="string" required>

<Description>

The contact's email address. Trimmed and lowercased before it is stored and checked for uniqueness. Unique within the workspace.

</Description>

</Field>

<Field name="first_name" type="string">

<Description>

The contact's first name.

</Description>

</Field>

<Field name="last_name" type="string">

<Description>

The contact's last name.

</Description>

</Field>

<Field name="external_id" type="string">

<Description>

Your own identifier for this contact, such as a user ID in your system. Unique within the workspace when set.

</Description>

</Field>

<Field name="data" type="object">

<Description>

Custom property values for this contact. Each key must be a property created via the contact properties API, and each value must be a string, number, or boolean matching the property's declared type (strings up to 500 characters); a null value is ignored. Unregistered or archived keys are rejected with a validation error. Total size is capped at 2 KB serialized.

</Description>

</Field>

</Payload>

<Payload kind="response">

<Field name="id" type="string" required>

<Description>

ID of the contact (`con_`-prefixed), accepted by every operation that takes a `contact_id`.

</Description>

</Field>

<Field name="email" type="string" required>

<Description>

The contact's email address, stored trimmed and lowercased. Unique within the workspace.

</Description>

</Field>

<Field name="first_name" type="nullable string">

<Description>

The contact's first name. Available in broadcast templates as the `contact.first_name` variable.

</Description>

</Field>

<Field name="last_name" type="nullable string">

<Description>

The contact's last name. Available in broadcast templates as the `contact.last_name` variable.

</Description>

</Field>

<Field name="external_id" type="nullable string">

<Description>

Your own identifier for this contact, such as a user ID in your system. Unique within the workspace when set.

</Description>

</Field>

<Field name="data" type="object">

<Description>

Custom property values for this contact, available as template variables in broadcasts. Each key is a property created via the contact properties API, and each value is a string, number, or boolean matching the property's declared type (strings up to 500 characters). Total size is capped at 2 KB serialized. Values stored under a property that was later archived remain readable here.

</Description>

</Field>

<Field name="channels" type="array of string">

<Description>

Channels this contact can be reached on, derived from the identifiers it has. A contact with an email address includes `email`. More values are added as a contact gains identifiers for other channels.

</Description>

</Field>

<Field name="created_at" type="string" required />

<Field name="updated_at" type="string" required />

</Payload>