POST/contacts

POST /contacts

Create a new contact.

Request

curl -X POST 'https://api.sendheron.com/api/v1/contacts' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json'

The key must carry these:

Name	Type	Required	Description
email	string	Yes	Contact email address.
firstName	string	No	First name.
lastName	string	No	Last name.
properties	object	No	Arbitrary custom fields, stored as JSONB.
status	subscribed \| unsubscribed \| bounced \| complained	No	Initial subscription status. Defaults to `subscribed`.
source	manual \| import \| api \| form \| sync	No	How the contact was acquired.
tagIds	uuid[]	No	Tags to attach by id.
tagNames	string[]	No	Tags to attach by name. Names that do not exist yet are created.

Use PUT /contacts instead if the contact may already exist. POST fails on a duplicate email.

Returns 201 on success.

400: The payload failed validation, or the request is not valid for the current state. The body's `description` names the field and says what was wrong with it in words, e.g. "domain: domain must be a bare hostname such as acme.com, with no scheme, path, or port". The `error` code is stable and safe to branch on; `description` is for the human reading the log.
401: Missing or invalid API key.
403: Valid key, but it does not carry the required scope. The `error` code is `apiKeys.insufficientScopes` and the `description` names both halves of the problem: "Missing required scope(s): X. This key holds: Y." Neither is a secret, since the required scopes are on this page and the held ones are your own credential, and a bare "Forbidden" costs a debugging pass to work out which of the two it was.
404: No such record in this workspace. An id belonging to a different workspace returns this too, never a 403, because the API will not confirm that a record exists outside the workspace your key was issued in. Read it as "not yours or not there" rather than as "definitely gone".
409: A duplicate, or an idempotency key reused with a different payload.
429: Either rate-limit ceiling was exceeded.

100/min per key, counted against the organization's WRITE ceiling (400/min). Both windows are one minute. There is no hourly or daily quota.