List the caller's phone numbers
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.
Authorization
oauth2 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
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/user/settings/phones"{ "phone_numbers": [ { "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"}{ "code": "RATE_LIMIT_EXCEEDED", "description": "Too Many Requests"}{ "code": "INTERNAL_ERROR", "description": "Internal Server Error"}Send the primary email OTP POST
Sends or resends the owner-authorization or new-email OTP for the caller's primary-email change. The `otp` of the response tells where it went. A user token calls this on behalf of the signed-in user. Returns 404 when the email is not a contact on the caller's profile, and 409 when the current-account state changed and the flow must restart.
Add a phone number POST
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.