API · Contacts

Create Contact

Create a contact or update an existing contact with the same email address, ignoring case (requires full access). Supplied fields and segment memberships are merged into the contact.

POST/contactsFull access

Request parameters

Parameter	Type	Description
`Idempotency-Key` header · optional	`string` 1–256 characters	Makes the request safe to retry. See Idempotency.
`email` body · required	`string`	Email address, trimmed and lowercased, with at most 254 characters.
`first_name` body · optional	`string \| null`	First name, up to 1000 characters; null clears the name.
`last_name` body · optional	`string \| null`	Last name, up to 1000 characters; null clears the name.
`unsubscribed` body · optional	`boolean \| null`	Whether the contact is unsubscribed from all broadcasts; null leaves the setting unchanged.
`properties` body · optional	`object`	Existing property keys with matching string or number values up to 1000 characters; empty strings or individual null values reset to the fallback, while properties: null is rejected.
`segments` body · optional	`(object)[] \| null` Up to 500 items	Array of segment IDs to add the contact to.
`segments[].id` body · required	`string`	See operation behavior.
`topics` body · optional	`(object)[] \| null` Up to 100 items	Array of topic subscriptions for the contact.
`topics[].id` body · required	`string`	See operation behavior.
`topics[].subscription` body · required	`"opt_in" \| "opt_out"`	See operation behavior.
`audience_id` body · optional	`string`	Segment to join when segments is omitted.

Request example

Set OPENSEND_BASE_URL=https://api.example.com and OPENSEND_API_KEY=os_replace_me on your server.

bash

curl -X POST "$OPENSEND_BASE_URL/contacts" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"email":"ada@example.net","first_name":"Ada"}'

Response

201 · application/json. Example IDs stand for IDs returned by your installation.

json

{
  "object": "contact",
  "id": "YOUR_ID"
}

Behavior and errors

Creating a contact whose email already exists (ignoring case) merges the supplied fields and segment memberships into it; it does not replace the contact. The contact and its memberships and topic choices are committed together. Property keys must already exist as contact properties, with string or number values. The response status is 201.

Use a full-access credential. Resource IDs belong to your team; an unknown or foreign resource returns 404. See authentication, errors, rate limits, and compatibility for the shared contract.