AthausDocs

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/contacts

Parameters

Header

NameTypeRequiredDescription
Athaus-VersionstringnoOptional 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-KeystringnoMakes 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.

FieldTypeDescription
salutationstring | nullOne of ms, mr, mx.
firstNamestring | null
lastNamestring | null
companystring | null
emailstring | nullAt most one live contact per address in an office.
phonestring | null
streetstring | null
postalCodestring | null
citystring | null
tagsstring[]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

FieldTypeDescription
objectstringAlways contact.
idstringUUID of the contact.
salutationstring | nullOne of ms, mr, mx.
firstNamestring | null
lastNamestring | null
displayNamestringHow the contact is named in every list: last name first, or what makes the contact reachable.
companystring | null
emailstring | null
phonestring | null
streetstring | null
postalCodestring | null
citystring | null
tagsstring[]
sourcestringWhere the contact came from, for example manual, an import or a connected system.
createdAtstring (date-time)
updatedAtstring (date-time)

Response headers

HeaderDescription
Request-IdIdentifies this request. Quote it in a support request.
Athaus-VersionThe API version of this response: v1.
Athaus-ReleaseThe release of v1 that answered, for example 1.0. A label for support and changelogs; no request can select it.
ETagA 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-PolicyThe quota policy of the bucket that applies.
RateLimitRemaining quota and seconds until the bucket is full again.
Idempotent-Replayedtrue 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.

StatusCodesMeaning
400api_version_unsupported, invalid_bodyInvalid request.
401unauthorizedMissing or invalid API key.
403insufficient_permissions, plan_requiredThe key lacks a right, or the plan does not include API access.
404not_foundNothing under this ID.
409email_already_exists, idempotency_key_in_use, idempotency_outcome_unknownThe request conflicts with the state of the resource (for example a duplicate), or with an idempotency key.
413payload_too_largeThe request body is larger than 512 KB.
415invalid_inputThe request body is not JSON. Send Content-Type: application/json.
422idempotency_key_reusedThe idempotency key was already used with a different request body.
429rate_limitedRate limit exceeded.
500internal_errorServer error.

Keep reading

On this page