Skip to main content

API Documentation: Aloware Number Lookup API Integration

Use the Aloware Number Lookup API to get a phone number's carrier, line type and location from an LRN lookup: the endpoint and its fields, safe retries with an Idempotency-Key header, the response and its error codes.

Written by Laarni D

The Number Lookup API returns a phone number's carrier, line type and location from an LRN (Location Routing Number) lookup. Each lookup is billed.

To find it in Aloware Admin, click Integrations, then Number lookup under Contacts API. You can also open Integrations > Number lookup directly.

The Number lookup page under Contacts API in Aloware Admin


Before you start

Keep these points in mind before you call the API:

  • Requests sign in with your account's API token, shown on the Number lookup page. The API, MCP with a bearer token and Form Connect all use this token, so keep it secret.

  • Each lookup is billed. Using the API counts as automated, paid usage under Aloware's billing terms. For what a lookup costs, read Breaking down Aloware's ad-hoc charges.

  • Aloware acts on each request exactly as your integration sends it. Check what it sends and keep your own log of its requests.


Trying a lookup in Aloware Admin

Under Look up a number, type a number in Phone number and click Look up. Each lookup is billed, including the ones you run here.


Looking up a phone number

Send a POST request to /api/v1/webhook/lookup with these fields:

  • api_token (required): your account's API token.

  • phone_number (required): the phone number to look up.

The lookup endpoint, its fields and its retry header

Here is an example request:

curl -X POST \
https://app.aloware.io/api/v1/webhook/lookup \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "[API_TOKEN]",
"phone_number": "8181234567"
}'

Retrying a request

Add the optional Idempotency-Key header, up to 255 characters, to retry safely. A retry with the same key runs the request only once.

This is how repeats with the same key behave:

  • A repeat within 24 hours gets the first response, with the header Idempotent-Replayed: true.

  • A repeat gets HTTP 409 while the first request is still running, and HTTP 422 if the body is different.

  • If the first request has not finished after 5 minutes, a repeat gets HTTP 409 until it does, for up to 24 hours. Check whether it took effect, then retry with a new key.

  • Only successful responses are kept, so a retry after an error runs again.


Reading the response

A successful lookup returns HTTP 200 with the number's carrier, line type and location:

{
"sid": "4243942058",
"line_type": "1",
"carrier": "Sprint PCS/2",
"cnam_city": "Burbank",
"cnam_state": "CA",
"cnam_country": "US",
"data": {
"tn": "4243942058",
"lrn": "818795",
"ported_status": "Y",
"ported_date": "20190104222010",
"ocn": "6664",
"line_type": "1",
"spid": "6664",
"spid_carrier_name": "Sprint PCS/2",
"spid_carrier_type": "1",
"altspid": "",
"altspid_carrier_name": "",
"altspid_carrier_type": "",
"city": "BURBANK",
"state": "California",
"country": "United States"
}
}

line_type is the number's line type, and data.line_type takes the same values:

  • 0: Landline

  • 1: Wireless

  • 2: VOIP

  • 3: Other

To learn more about LRN in Aloware, read Understanding LRN: Location Routing Numbers in Aloware.

Error responses

The API returns these errors:

  • HTTP 400: the request is invalid, for example the phone number is missing. The response lists what failed.

  • HTTP 402: a trial account reached its LRN lookup limit.

  • HTTP 404: the lookup can't identify the number.

  • HTTP 500: the lookup failed.

Need another endpoint? Email [email protected].

Did this answer your question?