Create a contact
Request, parameters, response and errors of POST /v1/contacts.
Last updated:
Creates a contact. It needs an email address or a phone number. An email address belongs to one contact per office: a second contact with the same address is a 409 and changes nothing. The API never asks whether a similar name is a duplicate; only the email address decides. Send Idempotency-Key to make a retry safe. Needs write access to contacts.
Requires the scope propose and at least the level write on contacts. Only a key created by the management of the office gets this access.
Request
POST https://api.athaus.ai/v1/contactsParameters
Header
| Name | Type | Required | Description |
|---|---|---|---|
Athaus-Version | string | no | Optional and carries nothing a client needs: the version is the path. Accepted when it says v1 or 1. Any other value is a 400 api_version_unsupported. |
Idempotency-Key | string | no | Makes a retry safe: the same key with the same body returns the first answer and writes nothing twice. A random value of at least 128 bits, for example a UUID, 1 to 255 characters. The key is kept for 24 hours and scoped to the API key and this operation. The same key with a different body is a 422; while the first request still runs it is a 409. Only successful answers are kept: after an error the key is free again. |
Request body
JSON with Content-Type: application/json. A field the API does not know is a 400, and errors[].name names the field. The body is required.
| Field | Type | Description |
|---|---|---|
salutation | string | null | One of ms, mr, mx. |
firstName | string | null | |
lastName | string | null | |
company | string | null | |
email | string | null | At most one live contact per address in an office. |
phone | string | null | |
street | string | null | |
postalCode | string | null | |
city | string | null | |
tags | string[] | Replaces the whole list. Trimmed and de-duplicated, at most 30 are kept. |
Example
curl -X POST "https://api.athaus.ai/v1/contacts" \
-H "Authorization: Bearer ath_live_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"salutation":"ms","firstName":"Ada","lastName":"Weber","email":"ada.weber@example.com","phone":"+49 30 1234567","city":"Berlin","tags":["vip"]}'Response
On success the status is 201 with Contact.
Contact
| Field | Type | Description |
|---|---|---|
object | string | Always contact. |
id | string | UUID of the contact. |
salutation | string | null | One of ms, mr, mx. |
firstName | string | null | |
lastName | string | null | |
displayName | string | How the contact is named in every list: last name first, or what makes the contact reachable. |
company | string | null | |
email | string | null | |
phone | string | null | |
street | string | null | |
postalCode | string | null | |
city | string | null | |
tags | string[] | |
source | string | Where the contact came from, for example manual, an import or a connected system. |
createdAt | string (date-time) | |
updatedAt | string (date-time) |
Response headers
| Header | Description |
|---|---|
Request-Id | Identifies this request. Quote it in a support request. |
Athaus-Version | The API version of this response: v1. |
Athaus-Release | The release of v1 that answered, for example 1.0. A label for support and changelogs; no request can select it. |
ETag | A strong entity tag of this state of the resource. Send it as If-Match to change or delete the resource only if it is unchanged, or as If-None-Match to read it only if it changed. |
RateLimit-Policy | The quota policy of the bucket that applies. |
RateLimit | Remaining quota and seconds until the bucket is full again. |
Idempotent-Replayed | true when this is the stored answer to an earlier request with the same Idempotency-Key. |
Errors
Every error arrives as problem details. Branch on code, not on title or detail.
| Status | Codes | Meaning |
|---|---|---|
400 | api_version_unsupported, invalid_body | Invalid request. |
401 | unauthorized | Missing or invalid API key. |
403 | insufficient_permissions, plan_required | The key lacks a right, or the plan does not include API access. |
404 | not_found | Nothing under this ID. |
409 | email_already_exists, idempotency_key_in_use, idempotency_outcome_unknown | The request conflicts with the state of the resource (for example a duplicate), or with an idempotency key. |
413 | payload_too_large | The request body is larger than 512 KB. |
415 | invalid_input | The request body is not JSON. Send Content-Type: application/json. |
422 | idempotency_key_reused | The idempotency key was already used with a different request body. |
429 | rate_limited | Rate limit exceeded. |
500 | internal_error | Server error. |
Keep reading
REST API: authentication with an API key
Every call to /v1 carries an API key as a bearer token. Where to get one, which scopes it carries and what does not work.
REST API: errors as problem details
Every error from /v1 is an RFC 9457 problem with a real HTTP status, a code to branch on and a request id for support.