Update contact

PATCH

/v1/contacts/{emailMd5}

const url = 'https://api.optizmo.com/deploy/v1/contacts/93942e96f5acd83e2e047ad8fe03114d';
const options = {
  method: 'PATCH',
  headers: {Authorization: '<Authorization>', 'Content-Type': 'application/json'},
  body: '{"attributes":{"first_name":"Alice","nickname":null}}'
};

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

curl --request PATCH \
  --url https://api.optizmo.com/deploy/v1/contacts/93942e96f5acd83e2e047ad8fe03114d \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "attributes": { "first_name": "Alice", "nickname": null } }'

Applies an RFC 7386 JSON Merge Patch to the contact’s schema attributes via the attributes field: a value sets the attribute, null removes it, and attributes absent from the body are left untouched. The identity email attribute and the brand attribute are rejected with 400. To manage a contact’s brand subscriptions use the subscriptions endpoints.

Authorizations

optizmo_api_key

Parameters

Path Parameters

emailMd5

required

string

/^[A-Fa-f0-9]{32}$/

The contact identity: the MD5 hex digest of the lowercased email address, md5(lower(email)). Uppercase hex digests are accepted. For example, the contact with email Test@Email.com is addressed by md5('test@email.com') = 93942e96f5acd83e2e047ad8fe03114d.

Request Body^required

application/json

Update a contact’s schema attributes. The attributes object is keyed by schema attribute name: a value sets the attribute, null removes it, and absent attributes are left untouched. Empty-string values are rejected. The identity email attribute and the brand attribute (managed via the subscriptions) are rejected.

object

attributes

required

Schema attribute values keyed by attribute name; null removes the attribute.

object

key

additional properties

One of:

string

Example

{
  "attributes": {
    "first_name": "Alice",
    "nickname": null
  }
}

Responses

200

The updated 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

{
  "emailMd5": "b58996c504c5638798eb6b511e6f49af",
  "attributes": {
    "first_name": "Alice"
  },
  "brandIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "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"
}

404

No contact with this emailMd5 exists in your account.

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#not_found_error",
  "status": 404,
  "title": "Not found",
  "detail": "Contact not found",
  "code": "not_found_error",
  "instance": "/deploy/v1/contacts/93942e96f5acd83e2e047ad8fe03114d"
}

409

A bulk contact operation or schema change is in progress for this account (code: operation_in_progress). 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

Example

{
  "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/93942e96f5acd83e2e047ad8fe03114d"
}

Headers

Retry-After

integer

Seconds to wait before retrying.

Update contact

Authorizations

Parameters

Path Parameters

Request Body required

Example

Responses

200

Example

400

Example

401

Example

403

Example

404

Example

409

Example

Headers

Request Body^required