Phone Verification

Phone Verification checks that a phone number actually belongs to the person who claims it, using a carrier identity-match lookup. It compares the sender's name, address, and date of birth against the data the mobile carrier holds for that number and returns a match score. Use it as a fraud signal during onboarding or before a first transaction.

This check is diagnostic and explicit — it never runs automatically from the transaction flow, and it never rewrites the sender's stored phone number. Call it when you want a check.

Verifying a Phone Number

Endpoint: POST /organizations/{tenant}/v2/people/verifyPhone
Authentication: Agent-level (x-api-key + x-agent-id + x-agent-api-key)

There are two mutually exclusive calling modes:

⚠️ The modes cannot be combined. If you send personId, you must not send any inline identity field, or the request returns 422.

Person Mode

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/v2/people/verifyPhone \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "personId": "48066496-9445-41b7-acbe-85e069a77cb7"
}'

The sender's stored phoneNumber must already be in E.164 format, otherwise the request returns 422.

Inline Mode

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/v2/people/verifyPhone \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "phoneNumber": "+14145447770",
  "firstName": "John",
  "lastName": "Doe",
  "addressLine1": "123 Market St",
  "city": "San Francisco",
  "state": "CA",
  "postalCode": "94105",
  "addressCountryCode": "US",
  "dateOfBirth": "1990-01-15"
}'

Request Fields

More identity fields you provide means a more complete match result.

Response

{
  "verificationId": 42,
  "phoneNumber": "+14145447770",
  "status": "MATCH",
  "summaryScore": 100,
  "callerType": "CONSUMER",
  "valid": true,
  "nationalFormat": "(414) 544-7770",
  "countryCode": "US",
  "identityMatch": {
    "first_name_match": "exact_match",
    "last_name_match": "exact_match",
    "address_lines_match": "exact_match",
    "date_of_birth_match": "exact_match",
    "summary_score": 100
  },
  "verifiedAt": "2026-09-09T14:22:11+00:00",
  "cached": false
}

Status Thresholds

status is derived from summaryScore using per-tenant thresholds (defaults: MATCH ≥ 80, PARTIAL ≥ 40, below → NO_MATCH). The status is captured at verification time — later threshold changes do not re-bucket historical results. Contact Inyo to tune your thresholds.

Caching

Identical requests are cached per tenant for 90 days, keyed on the full input tuple (phone number, name, address, date of birth). A cache hit returns the stored result with "cached": true and does not re-bill the verification provider. Vary any input field to force a fresh lookup.

Error Responses

Sandbox Testing

In the sandbox, phone verification does not call the real provider — no billing, no live lookups. Instead, the outcome is driven entirely by the last digit of the phone number, so you can exercise every branch by choosing the number you send:

For example, +14145550002 returns MATCH, and +14145550009 returns 502.

Because the cache key includes the phone number, re-running the same sandbox number returns "cached": true on the second call. Change the number (or any other field) to force a fresh simulated lookup.

All Endpoints