Phone Ident

What Phone Ident does

Phone Ident enriches a phone number with identity-related information. Use contact discovery to retrieve available subscriber details, or contact matching to compare the identity supplied by your user with the data on file. Other optional modules add subscriber, porting, SIM-change and breach signals.

This is the Phone ID operation, not an OTP challenge and not a complete identity decision by itself. Phone Intelligence covers phone risk, live status and OTP verification. The KYC product overview explains how phone identification can fit alongside other identification routes.

Endpoint and authentication

POST /phone-service/phoneid, using the shared IDCanopy API environment and bearer token. Calls belong on your backend.

Request

Field	Required	Meaning
`phoneNumber`	Yes	Country code and national number, digits only: no plus sign, spaces or punctuation.
`accountLifecycleEvent`	No	`create`, `sign-in`, `transact`, `update` or `delete`.
`externalId`	No	Your correlation identifier, echoed in the response.
`originatingIp`	No	The end user's IPv4 or IPv6 address.
`addons`	No	Select the additional modules below.
`consent`	Required for certain modules	`method` and `timestamp`; see Consent below.

Minimal request with an illustrative test number, not a promise of source coverage:

curl --fail-with-body -X POST "$UMBRELLA_BASE_URL/phone-service/phoneid" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"15555550100","externalId":"phone-ident-example"}'

Optional identity and risk modules

Select modules inside addons, using the camelCase keys in this table. A selected module is an object, not a boolean. For modules with no documented input fields, the request shape is {}.

Key	Purpose	Documented input fields
`contact`	Retrieve available contact details; optional email can support cross-referencing.	`email`
`contactMatch`	Compare supplied name and address with the data on file.	`firstName`, `lastName`, `address`, `city`, `postalCode`, `state`, `country`, `inputUsed`
`contactPlus`	Request enhanced contact information.	`billingPostalCode`
`ageVerify`	Check an age threshold where supported.	`ageThreshold`
`breachedData`	Check known breach exposure associated with the number.	No input fields specified.
`callForwardDetection`	Check forwarding status and conditions.	No input fields specified.
`numberDeactivation`	Request deactivation information.	See the contract caveat below.
`subscriberStatus`	Request subscriber account type, status and tenure information.	No input fields specified.
`portingHistory`	Request number-porting history.	`pastXDays`
`portingStatus`	Request current porting and network information.	No input fields specified.
`simSwap`	Request SIM-change information.	No input fields specified.

Availability and returned detail vary by country, network and enabled modules. Contact discovery and contact matching are different: a source can support matching without disclosing the underlying address or date of birth. Do not assume every listed field is returned for every number.

Obtain the required user consent before querying consent-dependent data, including contact matching and call-forwarding information. The request has a consent object with a numeric method (1, 2, 3 or 4) and an ISO 8601 timestamp. The published schema does not explain the method-code meanings or map consent requirements to every module. Confirm the applicable method and collection requirements with IDCanopy before integration.

Response and interpretation

Field	Meaning
`status`	Whether the API request itself succeeded; not an identity-match decision.
`data.referenceId`	Transaction reference for support and correlation.
`data.externalId`	Your echoed reference, if supplied.
`data.status`	Processing code, description and update time.
`data.phoneType`, `data.carrier`, `data.numbering`	Phone type, network and number-normalisation information.
`data.blocklisting`, `data.location`	Available blocklisting and location context; not proof of the user's current physical location.

Use contact-match evidence with your KYC policy and other signals. A successful lookup, a missing value or an unavailable module is not a positive identity match. If your integration requires information that is not available, route it to another verification method or review.

Pending verification: the published response schema defines the base lookup but not the module-specific result objects. Exact match-score fields, age-check coverage and thresholds, and SIM-swap risk mappings are not established by this contract. The numberDeactivation request schema also contains response-like fields; confirm its intended input before sending them. Date-of-birth matching and a last-verified date are not defined request fields in the current contract.

Errors

The operation documents 400 for a malformed request, 401 for authentication failure, 404 for a missing resource, 429 for rate limiting, and 500 or 503 for service issues. Do not treat a technical failure as identity evidence.

Reference

The Phone reference includes the Phone ID operation, its schemas and related phone services. Use the published camelCase request keys rather than translating older snake_case examples directly.

Phone Ident

On this page