Create contact

POST

/v1/contacts

const url = 'https://api.optizmo.com/deploy/v1/contacts';
const options = {
  method: 'POST',
  headers: {Authorization: '<Authorization>', 'Content-Type': 'application/json'},
  body: '{"email":"user@example.com","brandIds":["497f6eca-6276-4993-bfeb-53cbbbba6f08"],"attributes":{"first_name":"Alice"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.optizmo.com/deploy/v1/contacts \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "email": "user@example.com", "brandIds": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "attributes": { "first_name": "Alice" } }'

Adds a contact to your contacts. If a contact with the same email already exists the request is rejected with 409 contact_exists. Please use the attributes present in the contact schema defined in the portal. This can also be retrieve from GET /deploy/v1/contact-schema.

Authorizations

optizmo_api_key

Request Body^required

application/json

The contact to create. Schema attribute values are provided in the attributes object; attribute keys must exist in your account’s contact schema (see GET /deploy/v1/contact-schema). The brand attribute key is rejected; brand subscriptions are set via brandIds. Derived name:subKey keys (e.g. email:md5) are computed by Optizmo and rejected. Empty-string values are rejected.

object

email

required

The contact’s email address in plaintext. The contact identity is derived from it and cannot be changed later.

string format: email

brandIds

Optional list of brands to subscribe the contact to. Every brand must be an existing brand in your account. Retreive brand ids from GET /deploy/v1/brands

Array<string>

>= 1 items <= 100 items unique items

attributes

Custom schema attribute values, keyed by attribute name.

object

key

additional properties

One of:

string
boolean

string

Example

{
  "email": "user@example.com",
  "brandIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "attributes": {
    "first_name": "Alice"
  }
}

Responses

201

The created contact.

application/json

A contact in your account.

object

email

required

The contact’s email address.

string format: email

emailMd5

required

The contact identity, md5(lower(email)), used in single-contact request paths.

string

/^[a-f0-9]{32}$/

attributes

required

Schema attribute values keyed by attribute name. Attributes of type email additionally expand into one read-only name:subKey entry per derived sub-attribute (e.g. name:md5, name:domain). The identity email and the brand subscriptions are surfaced via the dedicated email and brandIds fields instead of appearing here.

object

key

additional properties

One of:

string

brandIds

required

Ids of the brands the contact is subscribed to. May include ids of brands that have since been deleted from the account; resolve names via GET /deploy/v1/contacts/{emailMd5}/subscriptions or GET /deploy/v1/brands.

Array<string>

enabled

required

False when the contact has been disabled via POST /deploy/v1/contacts/{emailMd5}/disable.

boolean

createdAt

required

Timestamp at which the contact was first added.

string format: date-time

Example

{
  "email": "user@example.com",
  "emailMd5": "b58996c504c5638798eb6b511e6f49af",
  "attributes": {
    "first_name": "Alice"
  },
  "brandIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "enabled": true,
  "createdAt": "2026-06-12T00:00:00Z"
}

400

Invalid request payload. Details are provided in the error response.

application/json

Error envelope returned by every v1 endpoint for failures, following RFC 9457 Problem Details with code and errors extensions.

object

type

required

URI identifying the problem type; dereferences to its documentation.

string format: uri

status

required

HTTP status code applicable to this problem.

integer

title

required

Short, human-readable summary of the problem type.

string

detail

required

Detailed explanation specific to this occurrence.

string

code

required

Error code identifying the specific error condition.

string

Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error api_error contact_exists operation_in_progress

instance

URI reference identifying this specific occurrence (the request URI).

string format: uri-reference

errors

Provides additional information when the error relates to specific request fields.

Array<object>

object

detail

required

Detailed explanation for this specific field error.

string

pointer

JSON Pointer (RFC 6901) to the request body value that caused the error (e.g. /email, /attributes/firstName).

string

parameter

The URI query parameter that caused the error (e.g. pageSize, name[invalid]).

string

Example

{
  "type": "https://docs.optizmo.com/deploy/error-codes#invalid_request_error",
  "status": 400,
  "title": "Invalid request",
  "detail": "\"nickname\" is not an attribute in the contact schema",
  "code": "invalid_request_error",
  "instance": "/deploy/v1/contacts",
  "errors": [
    {
      "detail": "\"nickname\" is not an attribute in the contact schema",
      "pointer": "/attributes/nickname"
    }
  ]
}

401

Missing or invalid API key.

application/json

Error envelope returned by every v1 endpoint for failures, following RFC 9457 Problem Details with code and errors extensions.

object

type

required

URI identifying the problem type; dereferences to its documentation.

string format: uri

status

required

HTTP status code applicable to this problem.

integer

title

required

Short, human-readable summary of the problem type.

string

detail

required

Detailed explanation specific to this occurrence.

string

code

required

Error code identifying the specific error condition.

string

Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error api_error contact_exists operation_in_progress

instance

URI reference identifying this specific occurrence (the request URI).

string format: uri-reference

errors

Provides additional information when the error relates to specific request fields.

Array<object>

object

detail

required

Detailed explanation for this specific field error.

string

pointer

JSON Pointer (RFC 6901) to the request body value that caused the error (e.g. /email, /attributes/firstName).

string

parameter

The URI query parameter that caused the error (e.g. pageSize, name[invalid]).

string

Example

{
  "type": "https://docs.optizmo.com/deploy/error-codes#authentication_error",
  "status": 401,
  "title": "Authentication failed",
  "detail": "credentials required",
  "code": "authentication_error",
  "instance": "/deploy/v1/contacts"
}

403

Permission denied.

application/json

Error envelope returned by every v1 endpoint for failures, following RFC 9457 Problem Details with code and errors extensions.

object

type

required

URI identifying the problem type; dereferences to its documentation.

string format: uri

status

required

HTTP status code applicable to this problem.

integer

title

required

Short, human-readable summary of the problem type.

string

detail

required

Detailed explanation specific to this occurrence.

string

code

required

Error code identifying the specific error condition.

string

Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error api_error contact_exists operation_in_progress

instance

URI reference identifying this specific occurrence (the request URI).

string format: uri-reference

errors

Provides additional information when the error relates to specific request fields.

Array<object>

object

detail

required

Detailed explanation for this specific field error.

string

pointer

JSON Pointer (RFC 6901) to the request body value that caused the error (e.g. /email, /attributes/firstName).

string

parameter

The URI query parameter that caused the error (e.g. pageSize, name[invalid]).

string

Example

{
  "type": "https://docs.optizmo.com/deploy/error-codes#permission_error",
  "status": 403,
  "title": "Permission denied",
  "detail": "api key required",
  "code": "permission_error",
  "instance": "/deploy/v1/contacts"
}

409

Returned with code: contact_exists when a contact with this email already exists (including a disabled contact), or with code: operation_in_progress when a bulk contact operation or schema change is in flight for the account. In that case retry after the number of seconds given in the Retry-After header.

application/json

Error envelope returned by every v1 endpoint for failures, following RFC 9457 Problem Details with code and errors extensions.

object

type

required

URI identifying the problem type; dereferences to its documentation.

string format: uri

status

required

HTTP status code applicable to this problem.

integer

title

required

Short, human-readable summary of the problem type.

string

detail

required

Detailed explanation specific to this occurrence.

string

code

required

Error code identifying the specific error condition.

string

Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error api_error contact_exists operation_in_progress

instance

URI reference identifying this specific occurrence (the request URI).

string format: uri-reference

errors

Provides additional information when the error relates to specific request fields.

Array<object>

object

detail

required

Detailed explanation for this specific field error.

string

pointer

JSON Pointer (RFC 6901) to the request body value that caused the error (e.g. /email, /attributes/firstName).

string

parameter

The URI query parameter that caused the error (e.g. pageSize, name[invalid]).

string

Examples

A contact with this email already exists

{
  "type": "https://docs.optizmo.com/deploy/error-codes#contact_exists",
  "status": 409,
  "title": "Conflict",
  "detail": "A contact with this email already exists",
  "code": "contact_exists",
  "instance": "/deploy/v1/contacts"
}

A bulk operation blocks the mutation

{
  "type": "https://docs.optizmo.com/deploy/error-codes#operation_in_progress",
  "status": 409,
  "title": "Conflict",
  "detail": "A bulk contact operation or schema change is in progress for this account, retry later",
  "code": "operation_in_progress",
  "instance": "/deploy/v1/contacts"
}

Headers

Retry-After

integer

Seconds to wait before retrying. Present only when code is operation_in_progress.

Create contact

Authorizations

Request Body required

Example

Responses

201

Example

400

Example

401

Example

403

Example

409

Examples

Headers

Request Body^required