Cowdidocs
API ReferenceContact details

Add a phone number

POST
/v1/user/settings/phones

A user token matches the caller's first and last name against the mobile carrier's registered account name, then adds a global pending phone number and sends an OTP for the caller to confirm; no contact or SMS is created when the name check fails. Pending contacts do not reserve the identity; the first caller to verify a value wins the global claim. Five invalid OTP confirmations lock the contact until a platform admin resets it. Returns 400 when the caller already has the maximum number of phone contacts, 422 when the registered name does not match the caller's profile name or the profile has no first and last name, and 503 when the carrier lookup is temporarily unavailable. The first phone number of a caller with no primary phone number becomes the primary phone number when its verification completes.

Authorization

oauth2
AuthorizationBearer <token>

Create a client with POST /v1/oauth/clients, then exchange its credentials for an access token. AUTHORIZATION_CODE clients act on behalf of a signed-in user and always use PKCE; CLIENT_CREDENTIALS clients act as themselves. A client may only be granted scopes its creator already holds — read the grantable list from GET /v1/oauth/clients/scopes.

In: header

Request Body

application/json

The phone number to add as a pending contact on the caller's profile.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/user/settings/phones" \  -H "Content-Type: application/json" \  -d '{    "phone_number": "+254712345678"  }'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "value": "jane@example.com",  "otp": {    "step": "OWNER_AUTHORIZATION",    "sent_to": "EMAIL",    "steps": 2,    "digits": 6  },  "is_primary": true,  "validated": true,  "validated_at": "2026-01-15T09:20:00Z",  "requires_verification": true,  "verification_locked": true,  "verification_locked_at": "2026-01-20T16:45:00Z",  "created_at": "2026-09-01T10:15:30Z"}
{  "code": "BAD_REQUEST",  "description": "Bad Request"}
{  "code": "UNAUTHORISED",  "description": "Unauthorised"}
{  "code": "FORBIDDEN",  "description": "Forbidden"}
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "value": "jane@example.com",  "otp": {    "step": "OWNER_AUTHORIZATION",    "sent_to": "EMAIL",    "steps": 2,    "digits": 6  },  "is_primary": true,  "validated": true,  "validated_at": "2026-01-15T09:20:00Z",  "requires_verification": true,  "verification_locked": true,  "verification_locked_at": "2026-01-20T16:45:00Z",  "created_at": "2026-09-01T10:15:30Z"}
{  "code": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}
{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

List the caller's phone numbers GET

Returns the caller's phone number contacts across every organization. Includes both pending and validated numbers. A user token calls this on behalf of the signed-in user.

Delete a phone number DELETE

Deletes a non-primary phone number from the caller's profile after recent authentication. Returns 400 when the number is the caller's primary contact or their only phone number. A user token calls this on behalf of the signed-in user. Returns 404 when the contact does not exist, and 409 when the number is the target of a primary-contact change in progress.