Phone Intelligence
Choose between live phone status, transaction-risk scoring, identity enrichment and OTP verification
Choose the phone service
A phone number can support different questions: is the line reachable, does subscriber information match an identity, how risky is this transaction, or can the user receive a verification code? These are separate checks, not interchangeable proofs of identity.
The KYC overview places phone identification alongside other identification routes. The Risk Intelligence overview explains the wider risk context. Combine the signals your case needs rather than treating one score as a complete onboarding decision.
| Question | Operation | Guide |
|---|---|---|
| Is the line active, reachable or roaming? | POST /phone-service/phoneStatus | Live status |
| What identity-related information is linked to the number? | POST /phone-service/phoneid | Phone Ident |
| How risky is a particular account event or transaction? | POST /phone-service/phoneRiskScore | Risk scoring |
| Can I obtain combined risk and phone context from the number? | POST /phone-service/fullPhoneIntelligence | Full intelligence |
| Can the user receive and return an OTP? | POST /phone-service/verification, then PATCH /phone-service/verification/{referenceId} | OTP verification |
All operations use the shared IDCanopy API environments and bearer token. Keep credentials and requests on your backend.
Live phone status
POST /phone-service/phoneStatus accepts phoneNumber in E.164 format, including the country code.
It reports line and device status, not the identity of the person using the number.
{ "phoneNumber": "+15555550100" }Inspect status.code and errors for processing, then the returned evidence:
| Field | Meaning |
|---|---|
live.subscriberStatus | Whether the line is active or disconnected, where available. |
live.deviceStatus | Device reachability, where available. |
live.roaming, live.roamingCountry, live.roamingCountryIso2 | Available roaming information; an unavailable value is not a negative finding. |
phoneType, carrier, numbering | Line type, network and number-normalisation context. |
blocklisting | Returned blocklisting information. |
This response is not wrapped in the status boolean plus data envelope used by the other phone
operations. Do not interpret general location metadata as a current device-location fix.
Phone Ident
POST /phone-service/phoneid provides the identity-enrichment route. Select optional modules for
contact discovery, contact matching, age verification and related subscriber or risk signals.
See the Phone Ident API guide for request fields,
module selection, consent and response limitations. Phone Ident uses a digits-only number format,
unlike the E.164 examples for status and risk.
Transaction-risk scoring
POST /phone-service/phoneRiskScore evaluates the phone number in the context of an account event.
Use it when deciding whether to continue, request another check or send the case to review.
| Field | Required | Meaning |
|---|---|---|
phoneNumber | Yes | Phone number including country code, in E.164 format. |
accountLifecycleEvent | Yes | create, sign-in, transact, update or delete. |
externalId | No | Your correlation identifier. |
originatingIp | No | The end user's IPv4 or IPv6 address, not your server's address. |
deviceId, accountId, emailAddress | No | Additional context for the account event; case-sensitive. |
{
"phoneNumber": "+15555550100",
"accountLifecycleEvent": "create",
"externalId": "phone-risk-example",
"originatingIp": "203.0.113.45"
}Use the schema field phoneNumber, not phone.
Read the risk result
The outer status boolean indicates whether the API request succeeded. The assessment is inside
data, alongside the processing status and phone context:
| Field | Meaning |
|---|---|
data.risk.score | Numeric transaction-risk score. |
data.risk.level | Returned risk-level label. |
data.risk.recommendation | Returned action recommendation, to apply with your own risk policy. |
data.riskInsights | Reason-code groups explaining the available signals. |
The insight groups are category (overall category), a2P (application-to-person activity),
p2P (person-to-person activity), numberType, ip and email. These are arrays of numeric codes,
not independent pass/fail flags. Limited activity can mean insufficient evidence rather than fraud.
A missing signal is not a positive trust signal.
Pending verification: numeric score bands and the complete reason-code dictionary are not defined by the published schema. Do not derive production cutoffs from an example response. Confirm the interpretation for your integration with IDCanopy.
Full phone intelligence
POST /phone-service/fullPhoneIntelligence accepts a required phoneNumber in E.164 format.
The operation combines phone context and risk assessment without the separate account-event inputs
of phoneRiskScore.
Its documented response includes data.risk, data.riskInsights, number, network, location and
blocklisting information. It does not establish that every optional Phone ID module is included.
Choose Phone Ident explicitly when your integration needs contact matching or another identity module.
OTP verification
OTP verification checks receipt of a code, not the subscriber's legal identity or the absence of account-takeover risk.
POST /phone-service/verificationstarts the verification. Setmethodtosmswith a digits-onlyphoneNumber, oremailwith the requiredemailfield.- Keep
data.referenceIdfrom the response. The initial request can be successful while code verification is still in progress. - After the user enters the code, send
PATCH /phone-service/verification/{referenceId}with{ "securityFactor": "123456" }, replacing the illustrative code with the user's input. - Read the verification result in
data.status, not just the outer success boolean. The published verified example has code3900and descriptionVerified.
The initiation request also supports externalId, messageTemplate, voiceLang and an optional
custom numeric securityFactor of 3 to 10 digits. If omitted, the schema describes an automatically
generated six-digit code. Do not place OTPs in logs or analytics.
The current API contract documents SMS and email for this operation. It does not document number masking, silent authentication, push verification or additional messaging-channel endpoints here. Contact IDCanopy to discuss services beyond this contract.
Test cases and errors
Live phone test cases and coverage details are not available here yet. Contact IDCanopy at office@idcanopy.com. Illustrative phone numbers and responses are not evidence of a live result.
Use HTTP errors for request or service failures and the operation's inner status for processing results. Do not turn a timeout, missing field or unavailable data source into an identity approval or a fraud finding. The reference lists the errors for each operation.
Reference
The operations of this topic and the token call. The full IDCanopy API reference has every topic.
Send request against Production or Sandbox needs a bearer token from
POST /authand a server-side or allowed origin. In the browser, use Mock.