---
title: "Recognize a message sender by phone candidates"
method: POST
path: "/v1/auth/sign-in/recognize-phone"
tags: ["Auth"]
---

# Recognize a message sender by phone candidates

`POST /v1/auth/sign-in/recognize-phone`

## Request

- Base URL: `https://api.configure.dev`
- URL: `https://api.configure.dev/v1/auth/sign-in/recognize-phone`
- Auth: API key in header `X-API-Key`

Trusted message-agent endpoint for recognizing phone-like sender IDs. A token is returned only when the user has approved the acting agent.

## Headers

- `X-Agent` string

## Request body

- SignInPhoneRecognitionRequest
  - `candidates` string[]: Phone-like sender IDs such as E.164, tel:, sms:, imessage:, or formatted phone strings.

## Response `200`

Phone recognition result.

- SignInPhoneRecognitionResponse
  - `matched` boolean, required
  - `recognized` boolean
  - `approved` boolean, required
  - `linked` boolean
  - `token` string: Present only when approved and linked are true.
  - `agentToken` string: Alias for token.
  - `userId` string
  - `agent` string
  - `displayName` string, nullable
  - `phoneCandidateCount` integer, required

## Other responses

- `400`: Request shape is invalid.
- `403`: Forbidden. Common causes include secret_key_required, token_wrong_type, approval_required, or access_denied.

---

[API](https://skmtc.dev/configure/apis/configure-http-api.md) · [All operations](https://skmtc.dev/configure/apis/configure-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/configure/apis/configure-http-api/revisions/ec760a9533d2?raw)