API Documentation

Welcome to the TelcoSignal API documentation. Here you'll find everything you need to integrate our powerful telco APIs into your applications.

Authentication

TelcoSignal uses API Keys to authenticate requests. You can view and manage your API Keys in the dashboard.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. Your API Key must be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer YOUR_API_KEY

API Reference

Our API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

SIM Swap API

Check if a SIM card associated with a phone number has been swapped recently.

POST

/v1/sim-swap/check

Request Body

Parameter	Type	Description
`phoneNumber`	string	The phone number to check, in E.164 format.
`maxAge`	int	Number of past hours to look back when checking if a SIM swap event occurred for the phone number (0–240 hours).

Example Request

curl -X POST https://api.telcosignal.com/v1/sim-swap/check \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "phoneNumber": "+919876543210",
  "maxAge": 72
}'

Example Response

{
  "txnId": "3f9c1e2a-6b7d-4e21-9a10-2c8f6d0b7a55",
  "phoneNumber": "+919876543210",
  "simSwapDetected": false,
  "maxAge": 240,
  "evaluatedAt": "2026-08-13T10:15:32Z"
}

Device Swap API

Detect if the device associated with a phone number has recently changed.

POST

/v1/device-swap-check

Request Body

Parameter	Type	Description
`phoneNumber`	string	The phone number to check, in E.164 format.
`maxAge`	int	Number of past hours to look back when checking if a device swap event occurred for the phone number (0–240 hours).

Example Request

curl -X POST https://api.telcosignal.com/v1/device-swap-check \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "phoneNumber": "+919876543210",
  "maxAge": 240
}'

Example Response

{
  "txnId": "3f9c1e2a-6b7d-4e21-9a10-2c8f6d0b7a55",
  "phoneNumber": "+919876543210",
  "deviceSwapDetected": false,
  "maxAge": 240,
  "evaluatedAt": "2026-08-13T10:15:32Z"
}

Location Verify API

Verify a phone number's network-reported location against a claimed coordinate.

POST

/v1/location-verify

Request Body

Parameter	Type	Description
`phoneNumber`	string	The phone number to check, in E.164 format.
`lat`	float	Claimed latitude (-90 to 90).
`lon`	float	Claimed longitude (-180 to 180).
`radius`	int	Match radius in meters (1–50000).
`maxAge`	int	Number of past seconds to look back for a location fix (0–3600 seconds).

Example Request

curl -X POST https://api.telcosignal.com/v1/location-verify \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "phoneNumber": "+919876543210",
  "lat": 28.6139,
  "lon": 77.2090,
  "radius": 2000,
  "maxAge": 60
}'

Example Response

{
  "txnId": "3f9c1e2a-6b7d-4e21-9a10-2c8f6d0b7a55",
  "phoneNumber": "+919876543210",
  "locationMatch": true,
  "radiusMeters": 2000,
  "evaluatedAt": "2026-08-13T10:15:32Z"
}

Device Roaming Status API

Check whether a phone number is currently roaming outside its home network.

POST

/v1/device-roaming-status

Request Body

Parameter	Type	Description
`phoneNumber`	string	The phone number to check, in E.164 format.

Example Request

curl -X POST https://api.telcosignal.com/v1/device-roaming-status \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "phoneNumber": "+919876543210"
}'

Example Response

{
  "txnId": "3f9c1e2a-6b7d-4e21-9a10-2c8f6d0b7a55",
  "phoneNumber": "+919876543210",
  "roamingDetected": false,
  "currentCountry": "GB",
  "evaluatedAt": "2026-08-13T10:15:32Z"
}

KYC Tenure API

Look up how long a phone number has been registered with the telco.

POST

/v1/kyc-tenure-check

Request Body

Parameter	Type	Description
`phoneNumber`	string	The phone number to look up, in E.164 format.

Example Request

curl -X POST https://api.telcosignal.com/v1/kyc-tenure-check \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "phoneNumber": "+919876543210"
}'

Example Response

{
  "txnId": "3f9c1e2a-6b7d-4e21-9a10-2c8f6d0b7a55",
  "phoneNumber": "+919876543210",
  "tenureDays": 842,
  "evaluatedAt": "2026-08-13T10:15:32Z"
}

Call Forwarding API

Check if a phone number has call forwarding or diverts active.

POST

/v1/call-forwarding-check

Request Body

Parameter	Type	Description
`phoneNumber`	string	The phone number to check, in E.164 format.

Example Request

curl -X POST https://api.telcosignal.com/v1/call-forwarding-check \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "phoneNumber": "+919876543210"
}'

Example Response

{
  "txnId": "3f9c1e2a-6b7d-4e21-9a10-2c8f6d0b7a55",
  "phoneNumber": "+919876543210",
  "callForwardingDetected": true,
  "forwardingNumber": "+918765432109",
  "evaluatedAt": "2026-08-13T10:15:32Z"
}

Trust Score API

Evaluates the trustworthiness of a mobile number using multiple telco and identity signals in a single API request.

Trust Score by Mobile Number

Evaluates the trustworthiness of a mobile number using multiple telco and identity signals in a single API request.

POST

/v1/combined-check

The API automatically performs the following checks for every request:

SIM Swap: detects recent SIM replacement activity
Device Swap: identifies recent changes in the device associated with the number
High-Risk Region: checks whether the number is associated with a high-risk geographic region
KYC Tenure: evaluates the length of time the number has been associated with a verified KYC identity
Number on Social: checks the number's presence and activity on supported social/messaging platforms
Call Forwarding: detects active call-forwarding activity

The API returns the individual results of each check along with an aggregated Trust Score (0–1000) and Risk Profile.

Request Body

Parameter	Type	Required	Description
`phoneNumber`	string	Yes	Mobile number to evaluate. Must be provided in E.164 format (e.g. `+919876543210`).

Example Request

curl -X POST https://api.telcosignal.com/v1/combined-check \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "phoneNumber": "+919876543210"
}'

Response

The response contains:

txnId: Unique identifier for the API transaction.
phoneNumber: Mobile number evaluated.
results: Individual results from each automated check. If a check cannot be completed, its result contains an error object.
stats.trustScore: Aggregated trust score ranging from 0 to 1000. Higher scores indicate a more trusted/low-risk number.
stats.riskProfile: Overall risk classification: Low Risk, Medium Risk, or High Risk.
evaluatedAt: UTC timestamp when the evaluation was performed.

Example Response

{
  "txnId": "3f9c1e2a-6b7d-4e21-9a10-2c8f6d0b7a55",
  "phoneNumber": "+919876543210",
  "results": {
    "simSwapCheck": { "simSwapDetected": false, "maxAge": 240, "evaluatedAt": "2026-08-13T10:15:32Z" },
    "deviceSwapCheck": { "deviceSwapDetected": false },
    "highRiskRegion": { "highRiskRegionDetected": false },
    "kycTenureCheck": { "tenureDays": 842 },
    "numberOnSocialCheck": { "whatsappActive": true, "evaluatedAt": "2026-08-13T10:15:32Z" },
    "callForwardingCheck": { "callForwardingDetected": false }
  },
  "stats": {
    "trustScore": 1000,
    "riskProfile": "Low Risk"
  },
  "evaluatedAt": "2026-08-13T10:15:32Z"
}

Silent Authentication

Silently verify that a customer possesses the phone number they claim, without sending an OTP. Start a session, redirect the customer to confirm over the mobile network, then poll for the verified result.

SilentID (Number Verification) API

Silently verify possession of a phone number over the mobile network -- an alternative to OTP. Unlike the checks above, this is a two-step flow: the customer confirms possession by visiting a link, so you start a session and then poll for the result.

1. Start a verification session

POST

/v1/silentid-start

Parameter	Type	Description
`phoneNumber`	string	The phone number to verify, in E.164 format.
`returnUrl`	string (optional)	Where to send the customer's browser back to once verification completes.

Example Request

curl -X POST https://api.telcosignal.com/v1/silentid-start \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "phoneNumber": "+919876543210",
  "returnUrl": "https://yourbank.com/kyc/callback"
}'

Example Response

{
  "sessionId": "3f9c1e2a-6b7d-4e21-9a10-2c8f6d0b7a55",
  "authorizationUrl": "https://telcosignal.pryvx.com/silentid/callback?...",
  "status": "awaiting_user"
}

Redirect your customer's browser to authorizationUrl. Once they complete verification there, they land back on your returnUrl.

This has to happen on the customer's phone, not a desktop browser -- network-based verification works by the mobile operator recognizing the request on the customer's own cellular data session, so it can only confirm a SIM it can actually see traffic from. If your flow starts on a desktop (e.g. a web checkout), render authorizationUrl as a QR code instead of a clickable link, and have the customer scan it with their phone.

2. Poll for the result

GET

/v1/silentid-status/{sessionId}

Example Request

curl https://api.telcosignal.com/v1/silentid-status/3f9c1e2a-6b7d-4e21-9a10-2c8f6d0b7a55 \
-H "X-API-Key: YOUR_API_KEY"

Example Response

{
  "sessionId": "3f9c1e2a-6b7d-4e21-9a10-2c8f6d0b7a55",
  "status": "verified",
  "verified": true
}

Implementation: Where & How

The following table provides a high-level overview of which APIs to use for specific use cases to achieve immediate financial impact.

API Use Case Summary

API Type	Primary Use Case	Immediate Financial Impact
Trust Score	One-call risk decisioning	Combines multiple signals into one score, cutting integration time and per-decision latency.
SilentID	OTP-less onboarding and login	Eliminates SMS OTP costs, delays and the risk of OTP interception.
SIM Swap	High-value transfers / Password resets	Detects recent SIM changes to prevent account takeover and fraudulent fund transfers.
Device Swap	New device linked to an account	Flags suspicious device changes before authorizing payouts or new device enrollment.
Location Verify	Geographic risk screening	Identifies location mismatches that can indicate fraudulent or unauthorized transactions.
Device Roaming Status	Cross-border transaction screening	Flags unexpected roaming that may indicate a stolen device or account takeover.
KYC Tenure	Subscriber tenure checks	Identifies newly activated numbers that may carry higher fraud risk, enabling tighter approval controls.
Call Forwarding	Call/OTP interception defense	Detects call redirection that could allow fraudsters to intercept authentication calls.