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": "+447911123456",
  "maxAge": 72
}'

Example Response

{
  "swapped": false,
  "lastSwapDate": "2023-01-15T10:30:00Z"
}

Number Verification API

Silently verify possession of a phone number without user input.

POST

/v1/number/verify

Request Body

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

Example Request

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

Example Response

{
  "verified": true,
  "phoneNumber": "+447911123456",
  "country": "GB",
  "lineType": "mobile"
}

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.

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": "+447911123456"
}'

Example Response

{
  "swapped": false,
  "lastSwapDate": "2023-05-10T11:00:00Z"
}

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": "+447911123456"
}'

Example Response

{
  "forwardingActive": true,
  "forwardingNumber": "+447911654321"
}

KYC Match API

Match user-provided KYC information against telco records.

POST

/v1/kyc/match

Request Body

Parameter	Type	Description
`phoneNumber`	string	The phone number to match, in E.164 format.
`name`	string	User's full name.
`address`	string	User's full address.

Example Request

curl -X POST https://api.telcosignal.com/v1/kyc/match \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "phoneNumber": "+447911123456",
  "name": "John Doe",
  "address": "123 High Street, London, WC1A 1AA"
}'

Example Response

{
  "matchStatus": "MATCH",
  "details": {
    "nameMatch": true,
    "addressMatch": 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
Number Verification	Frictionless login & onboarding	Eliminates SMS OTP costs and "interception" risks.
SIM Swap	High-value transfers / Password resets	Blocks account takeovers; prevents massive "siphoning" of funds.
KYC Match	New account openings	Cross-verifies bank records with telco subscriber data to block synthetic IDs.
Scam Signal	Real-time payment protection	Detects if a user is on a manipulative call while transferring money.