Sinch Number Lookup API

Overview

Queries phone numbers for carrier, line type, porting, SIM swap, VoIP detection, and reassigned number detection. Used for fraud prevention, routing, and data enrichment.

v2 Base URL:
```
https://lookup.api.sinch.com
```
v1 Base URL:
```
https://number-lookup.api.sinch.com
```
(legacy -- no OAuth2, no projectId)
Endpoint:
```
POST /v2/projects/{projectId}/lookups
```
Auth: OAuth2 (recommended) or HTTP Basic. See sinch-authentication.
One number per request. No batch endpoint.

Getting Started

Canonical curl Example

bash

curl -X POST \
  'https://lookup.api.sinch.com/v2/projects/YOUR_project_id/lookups' \
  -H 'Content-Type: application/json' \
  -u YOUR_key_id:YOUR_key_secret \
  -d '{
    "number": "+12025550134",
    "features": ["LineType", "SimSwap", "VoIPDetection", "RND"],
    "rndFeatureOptions": { "contactDate": "2025-01-01" }
  }'

For OAuth2, replace

-u

with

-H 'Authorization: Bearer YOUR_access_token'

For SDK setup (Node.js, Python, Java, .NET), see the Getting Started Guide.

Request

Field	Type	Required	Notes
`number`	string	Yes	Single E.164 number (with `+` prefix)
`features`	string[]	No	`LineType` (default), `SimSwap` , `VoIPDetection` (alpha), `RND` (alpha)
`rndFeatureOptions.contactDate`	string	If `RND` requested	`YYYY-MM-DD` format

Critical: If

features

is omitted, only

LineType

is returned. You must explicitly request

SimSwap

VoIPDetection

, or

RND

Response

Flat object (not an array). Each feature populates its own sub-object; unrequested features are

null

Top-level fields:

number

countryCode

(ISO 3166-1 alpha-2),

traceId

line
object:

Field	Type	Values
`carrier`	string	Carrier name, e.g. `"T-Mobile USA"`
`type`	string enum	`Landline` , `Mobile` , `VoIP` , `Special` , `Freephone` , `Other`
`mobileCountryCode`	string	MCC, e.g. `"310"`
`mobileNetworkCode`	string	MNC, e.g. `"260"`
`ported`	boolean	Whether ported
`portingDate`	string	ISO 8601 datetime
`error`	object\|null	Per-feature error ( `status` , `title` , `detail` , `type` )

simSwap
object:

Field	Type	Values
`swapped`	boolean	Whether SIM swap occurred
`swapPeriod`	string enum	`Undefined` , `SP4H` , `SP12H` , `SP24H` , `SP48H` , `SP5D` , `SP7D` , `SP14D` , `SP30D` , `SPMAX`
`error`	object\|null	Per-feature error

voIPDetection
object (alpha):

Field	Type	Values
`probability`	string enum	`Unknown` , `Low` , `Likely` , `High` -- not numeric
`error`	object\|null	Per-feature error

rnd
object (alpha):

Field	Type	Values
`disconnected`	boolean	Disconnected after `contactDate`
`error`	object\|null	Per-feature error

For full response schemas, see the API Reference.

Common Workflows

1. Fraud check before verification

Look up the number with
```
features: ["SimSwap", "VoIPDetection"]
```
If
```
simSwap.swapped
```
is
```
true
```
and
```
swapPeriod
```
is
```
SP4H
```
or
```
SP24H
```
→ flag as high risk
If
```
voIPDetection.probability
```
is
```
High
```
or
```
Likely
```
→ require additional verification
If either feature returns a non-null
```
error
```
→ fall back to the other feature's result for risk scoring
Otherwise → proceed with SMS/voice verification

2. Pre-send number hygiene

Look up the number with

features: ["LineType", "RND"]

(include

rndFeatureOptions.contactDate

)

If
```
rnd.disconnected
```
is
```
true
```
→ remove from contact list
Route based on
```
line.type
```
: SMS for
```
Mobile
```
, voice for
```
Landline
```

3. Combined lookup + verification

Look up the number with
```
features: ["LineType", "SimSwap"]
```
If
```
line.type
```
is
```
Landline
```
→ use voice verification instead of SMS
If
```
simSwap.swapped
```
is
```
true
```
→ skip SMS verification, use an alternative channel
See Combined Lookup + Verification for the full flow.

4. Multiple numbers

No batch endpoint. Use parallel requests:

javascript

const results = await Promise.all(
  numbers.map((number) => sinch.numberLookup.lookup({ number, features: ['LineType', 'SimSwap'] }))
);

Gotchas

features
must be explicit. Omitting it returns only
```
LineType
```
. SIM swap, VoIP, and RND require explicit opt-in.
VoIP probability is a string enum, not a 0–1 score. Values:
```
Unknown
```
,
```
Low
```
,
```
Likely
```
,
```
High
```
.
SIM swap periods are short codes like
```
SP24H
```
,
```
SP7D
```
-- not human-readable strings.
Partial failures are possible. Each feature sub-object has its own
```
error
```
. A lookup can succeed for
```
line
```
but fail for
```
simSwap
```
.
RND requires
contactDate
. Omitting
```
rndFeatureOptions
```
when requesting
```
RND
```
causes a
```
400
```
.
SIM swap depends on carrier support. Not available for all numbers or regions.
VoIPDetection and RND are alpha. Behavior may change.
Rate limiting.
```
429 Too Many Requests
```
when exceeded. Contact Sinch for tier info.
Non-obvious error codes:
```
402
```
means Account Locked (not payment required),
```
403
```
means the API is disabled for your project. If response includes a
```
403
```
, direct the user to check this documentation.

sinch-number-lookup-api

NPX Install

Tags

SKILL.md Content