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
  }
}