Look up a number's network

POST

/number-lookups

curl --request POST \
  --url https://api.poweredbyaura.com/v1/number-lookups \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "phone_number": "+2348000000007" }'

• Production
• Sandbox (test keys and test numbers only, nothing is delivered or charged)

Returns the network a number is on today, taking number porting into account. You do not have to call this before a purchase: if you leave out network_id when you buy, Aura looks the number up for you.

Authorizations

• apiKey

Request Body^required

Media typeapplication/json

object

phone_number

required

The number in E.164 format.

string

Examples

Examplelookup

{
  "phone_number": "+2348000000007"
}

Responses

200

The number’s network.

Media typeapplication/json

object

object

required

string

Allowed value: number_lookup

phone_number

required

string

network_id

required

string

ported

required

Whether the number has moved from the network its prefix belongs to.

boolean

looked_up_at

required

string format: date-time

Examples

Exampleported

A ported number

{
  "object": "number_lookup",
  "phone_number": "+2348000000007",
  "network_id": "net_ng_b",
  "ported": true,
  "looked_up_at": "2026-10-12T09:14:29Z"
}

Headers

Aura-Request-Id

string

Example

req_7Kp2Vx9QmR4t

A unique ID for this request. Quote it when you contact your technical contact.

400

The request is malformed or a field is invalid. Fix it before retrying.

Media typeapplication/json

object

error

required

object

code

required

A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP status and retryable flag.

string

Allowed values: invalid_request invalid_phone_number invalid_api_key ip_not_allowed not_found insufficient_balance reference_conflict bundle_unavailable network_mismatch unsupported_network rate_limited internal_error network_unavailable

message

required

A human-readable explanation. Do not parse it; use code.

string

param

The request field the error is about, when there is one.

string

retryable

required

Whether the same request can succeed if you retry it later.

boolean

request_id

required

string

details

Extra facts about the error, such as the existing purchase or the network’s status.

object

key

additional properties

any

Examples

ExampleinvalidPhoneNumber

{
  "error": {
    "code": "invalid_phone_number",
    "message": "phone_number must be in E.164 format, such as +2348000000001.",
    "param": "phone_number",
    "retryable": false,
    "request_id": "req_9Qd4Hs1XvB7n"
  }
}

Headers

Aura-Request-Id

string

Example

req_7Kp2Vx9QmR4t

A unique ID for this request. Quote it when you contact your technical contact.

401

The API key is missing, wrong or revoked.

Media typeapplication/json

object

error

required

object

code

required

A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP status and retryable flag.

string

Allowed values: invalid_request invalid_phone_number invalid_api_key ip_not_allowed not_found insufficient_balance reference_conflict bundle_unavailable network_mismatch unsupported_network rate_limited internal_error network_unavailable

message

required

A human-readable explanation. Do not parse it; use code.

string

param

The request field the error is about, when there is one.

string

retryable

required

Whether the same request can succeed if you retry it later.

boolean

request_id

required

string

details

Extra facts about the error, such as the existing purchase or the network’s status.

object

key

additional properties

any

Examples

ExampleinvalidKey

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "retryable": false,
    "request_id": "req_2Mz6Rt8KcW1p"
  }
}

Headers

Aura-Request-Id

string

Example

req_7Kp2Vx9QmR4t

A unique ID for this request. Quote it when you contact your technical contact.

422

The request is well formed but cannot be carried out. Nothing was bought.

Media typeapplication/json

object

error

required

object

code

required

A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP status and retryable flag.

string

Allowed values: invalid_request invalid_phone_number invalid_api_key ip_not_allowed not_found insufficient_balance reference_conflict bundle_unavailable network_mismatch unsupported_network rate_limited internal_error network_unavailable

message

required

A human-readable explanation. Do not parse it; use code.

string

param

The request field the error is about, when there is one.

string

retryable

required

Whether the same request can succeed if you retry it later.

boolean

request_id

required

string

details

Extra facts about the error, such as the existing purchase or the network’s status.

object

key

additional properties

any

Examples

{
  "error": {
    "code": "bundle_unavailable",
    "message": "Bundle bnd_ng_a_10gb_30d cannot be bought right now.",
    "param": "bundle_id",
    "retryable": false,
    "request_id": "req_4Np9Kx2ZsD6v"
  }
}

{
  "error": {
    "code": "network_mismatch",
    "message": "+2348000000007 is on net_ng_b, but bundle bnd_ng_a_1gb_1d is for net_ng_a.",
    "param": "bundle_id",
    "retryable": false,
    "request_id": "req_1Hb7Vc4MtQ9r",
    "details": {
      "detected_network_id": "net_ng_b"
    }
  }
}

Headers

Aura-Request-Id

string

Example

req_7Kp2Vx9QmR4t

A unique ID for this request. Quote it when you contact your technical contact.

429

Too many requests. Wait for Retry-After seconds, then retry.

Media typeapplication/json

object

error

required

object

code

required

A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP status and retryable flag.

string

Allowed values: invalid_request invalid_phone_number invalid_api_key ip_not_allowed not_found insufficient_balance reference_conflict bundle_unavailable network_mismatch unsupported_network rate_limited internal_error network_unavailable

message

required

A human-readable explanation. Do not parse it; use code.

string

param

The request field the error is about, when there is one.

string

retryable

required

Whether the same request can succeed if you retry it later.

boolean

request_id

required

string

details

Extra facts about the error, such as the existing purchase or the network’s status.

object

key

additional properties

any

Examples

ExamplerateLimited

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 2 seconds.",
    "retryable": true,
    "request_id": "req_6Yf2Pk8GwN4s"
  }
}

Headers

Aura-Request-Id

string

Example

req_7Kp2Vx9QmR4t

A unique ID for this request. Quote it when you contact your technical contact.

Retry-After

integer

Seconds to wait before retrying.

RateLimit-Limit

integer

Requests allowed in the current window.

RateLimit-Remaining

integer

Requests left in the current window.

RateLimit-Reset

integer

Seconds until the current window resets.