IDCanopy Developers
IDCanopy APIRisk Intelligence

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.

QuestionOperationGuide
Is the line active, reachable or roaming?POST /phone-service/phoneStatusLive status
What identity-related information is linked to the number?POST /phone-service/phoneidPhone Ident
How risky is a particular account event or transaction?POST /phone-service/phoneRiskScoreRisk scoring
Can I obtain combined risk and phone context from the number?POST /phone-service/fullPhoneIntelligenceFull 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:

FieldMeaning
live.subscriberStatusWhether the line is active or disconnected, where available.
live.deviceStatusDevice reachability, where available.
live.roaming, live.roamingCountry, live.roamingCountryIso2Available roaming information; an unavailable value is not a negative finding.
phoneType, carrier, numberingLine type, network and number-normalisation context.
blocklistingReturned 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.

FieldRequiredMeaning
phoneNumberYesPhone number including country code, in E.164 format.
accountLifecycleEventYescreate, sign-in, transact, update or delete.
externalIdNoYour correlation identifier.
originatingIpNoThe end user's IPv4 or IPv6 address, not your server's address.
deviceId, accountId, emailAddressNoAdditional 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:

FieldMeaning
data.risk.scoreNumeric transaction-risk score.
data.risk.levelReturned risk-level label.
data.risk.recommendationReturned action recommendation, to apply with your own risk policy.
data.riskInsightsReason-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.

  1. POST /phone-service/verification starts the verification. Set method to sms with a digits-only phoneNumber, or email with the required email field.
  2. Keep data.referenceId from the response. The initial request can be successful while code verification is still in progress.
  3. After the user enters the code, send PATCH /phone-service/verification/{referenceId} with { "securityFactor": "123456" }, replacing the illustrative code with the user's input.
  4. Read the verification result in data.status, not just the outer success boolean. The published verified example has code 3900 and description Verified.

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 /auth and a server-side or allowed origin. In the browser, use Mock.

On this page