Get a contact with its handles

Returns one contact by id along with its full handles array, ordered primary handles first and then oldest to newest.

Endpoint

GET https://api.dairo.app/v1/contacts/{contactId}

Returns one contact by id along with its full handles array, ordered primary handles first and then oldest to newest. contactId is the contact's UUID. Returns 404 for an unknown contact or one owned by another project. Requires the contacts:read scope.

Scope: contacts:read. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

cURL

curl "https://api.dairo.app/v1/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $DAIRO_API_KEY"

Path parameters

Name	Type	Required	Description
`contactId`	string	yes	The contact's ID.

Response

200 Success. Body: application/json, ContactDetailResponse.

Field	Type	Required	Description
`contact`	Contact	yes

200

{
  "contact": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "alias": null,
    "displayName": "string",
    "kind": "person",
    "isSelf": true,
    "info": null,
    "metadata": {},
    "avatarUrl": null,
    "handles": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "contactId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "channel": "string",
        "value": "string",
        "label": "production",
        "isPrimary": true,
        "verified": true,
        "metadata": {},
        "createdAt": "2026-10-19T09:30:00Z",
        "updatedAt": "2026-10-19T09:30:00Z"
      }
    ],
    "createdAt": "2026-10-19T09:30:00Z",
    "updatedAt": "2026-10-19T09:30:00Z"
  }
}

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`).

Get a contact with its handles

Request

Path parameters

Response

Errors

On this page