Create a contact
Creates a contact and returns it together with its handles array.
Creates a contact and returns it together with its handles array. Only displayName (1–200 characters) is required; kind defaults to person (or agent/self), alias is an optional project-unique @-handle matching ^[a-z0-9][a-z0-9._-]{0,63}$, and info accepts up to 10,000 characters of free-text notes. Pass a handles array to attach initial channel addresses in the same call — each is validated before the contact is written (an email handle must be an email address and is stored lowercased), so a malformed handle fails the whole request with 400 and creates nothing. A duplicate alias, or a handle whose (channel, value) already exists in the project, is rejected with 409. Requires the contacts:write scope.
Scope: contacts:write. Send the API key as a bearer token; Scopes lists what each one reaches.
Request
Headers
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | no | Optional idempotency key for safe retries of side-effecting operations. (max length 128) |
Body
Required, application/json: ContactCreateRequest.
| Field | Type | Required | Description |
|---|---|---|---|
displayName | string | yes | (min length 1, max length 200) |
alias | string | no | |
kind | "person", "agent", "self" | no | |
info | string | no | (max length 10000) |
avatarUrl | string | no | |
metadata | object | no | |
handles | array of ContactHandleInput | no |
Response
200 Success. Body: application/json, ContactDetailResponse.
| Field | Type | Required | Description |
|---|---|---|---|
contact | Contact | yes |
Errors
Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.
| Status | Meaning |
|---|---|
400 | The request is malformed or a value is invalid (invalid_request, invalid_domain, idempotency_key_mismatch). |
401 | The API key is missing or invalid. |
403 | The key lacks the scope this endpoint needs (scope_missing) or may not do this (not_permitted). |
404 | No such resource in this account (resource_not_found). |
422 | The request is well-formed but a field failed validation (validation_failed). |
429 | Rate limit, plan limit, budget or spend cap reached (rate_limited, plan_limit_reached, budget_exceeded, spend_cap_reached). |
500 | An unexpected error; retry with backoff, then contact support (internal_error). |
List contacts
Returns the project's contacts sorted by displayName (ties broken by id), one keyset page at a time.
Get the project self contact
Returns the project self contact — the @me recipient, seeded from the project owner with isSelf set to true and the reserved alias me — together with its handles.