Introduction

Base URL: https://www.numberyo.tech

This documentation aims to provide all the information you need to work with our API.

<aside>As you scroll, you'll see code examples for working with the API in different programming languages in the dark area to the right (or as part of the content on mobile).
You can switch the language used with the tabs at the top right (or from the nav menu at the top left on mobile).</aside>

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your token by visiting your dashboard and clicking Generate API token.

Endpoints

List user's checks

requires authentication

Returns the last 10 checks (HLR or Verify) of your account, with pagination.

Example request:

curl --request GET \
    --get "https://www.numberyo.tech/api/checks?page=2" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://www.numberyo.tech/api/checks"
);

const params = {
    "page": "2",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://www.numberyo.tech/api/checks';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'page' => '2',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://www.numberyo.tech/api/checks'
params = {
  'page': '2',
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()

Example response (200):


{
    "checks": [
        {
            "id": 42,
            "type": "HLR",
            "created_at": "2025-03-30T14:21:00.000000Z"
        }
    ],
    "pagination": {
        "current_page": 1,
        "total_pages": 4,
        "total": 32
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/checks

Headers

Authorization

Example: Bearer {YOUR_AUTH_KEY}

Content-Type

Example: application/json

Accept

Example: application/json

Query Parameters

page integer optional

The page number to retrieve. Example: 2

Get check results (HLR or Verify)

requires authentication

Returns the results of a specific check based on its type (HLR or Verify).

Example request:

curl --request GET \
    --get "https://www.numberyo.tech/api/checks/42/results" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://www.numberyo.tech/api/checks/42/results"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://www.numberyo.tech/api/checks/42/results';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://www.numberyo.tech/api/checks/42/results'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200):


{
    "type": "HLR",
    "results": [
        {
            "country_code": 32,
            "country_name": "Belgium",
            "operator_name": "Proximus NV van publiek recht",
            "msisdn": "32456789023",
            "ported": false,
            "reachable": true,
            "valid_number": true,
            "plmn": "20601",
            "mcc": "206",
            "mnc": "01",
            "imsi": "206010000000000",
            "local_format": "456789023",
            "msc": null,
            "original_operator_name": null,
            "number_requested": "32456789023",
            "created_at": "2025-03-30T12:41:00.000000Z"
        }
    ]
}

Example response (200):


{
  "type": "Verify",
  "results": [
    {
      "e164_format": "+32456789023",
      "valid_number": true,
      "number_carrier": "Proximus NV van publiek recht",
      ...
    }
  ]
}

Example response (400):


{
    "message": "Unsupported check type."
}

Example response (404):


{
    "message": "Check not found or access denied."
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/checks/{id}/results

Headers

Authorization

Example: Bearer {YOUR_AUTH_KEY}

Content-Type

Example: application/json

Accept

Example: application/json

URL Parameters

id integer

The ID of the check to retrieve. Example: 42

Create a new check (HLR or Verify)

requires authentication

This endpoint allows you to initiate a new check (either HLR or Verify) for a given phone number. Returns the result of the check immediately.

Example request:

curl --request POST \
    "https://www.numberyo.tech/api/checks" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"phone_number\": \"32456789023\",
    \"type\": \"HLR\"
}"

const url = new URL(
    "https://www.numberyo.tech/api/checks"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "phone_number": "32456789023",
    "type": "HLR"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://www.numberyo.tech/api/checks';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'phone_number' => '32456789023',
            'type' => 'HLR',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://www.numberyo.tech/api/checks'
payload = {
    "phone_number": "32456789023",
    "type": "HLR"
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (201):


{
    "status": true,
    "message": "Check successfully created.",
    "check": {
        "id": 123,
        "type": "HLR",
        "source": "API",
        "user_cost": "1.00",
        "created_at": "2025-03-30T14:10:23Z"
    },
    "results": {
        "type": "HLR",
        "results": [
            {
                "country_code": 32,
                "country_name": "Belgium",
                "operator_name": "Proximus NV van publiek recht",
                "msisdn": "32456789023",
                "ported": false,
                "reachable": true,
                "valid_number": true,
                "plmn": "20601",
                "mcc": "206",
                "mnc": "01",
                "imsi": "206010000000000",
                "local_format": "456789023",
                "msc": null,
                "original_operator_name": null,
                "number_requested": "32456789023",
                "created_at": "2025-03-30T12:41:00.000000Z"
            }
        ]
    }
}

Example response (422):


{
    "status": false,
    "message": "Error creating check.",
    "error": "You don't have enough credits to perform this action (X credits)."
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/checks

Headers

Authorization

Example: Bearer {YOUR_AUTH_KEY}

Content-Type

Example: application/json

Accept

Example: application/json

Body Parameters

phone_number string

The phone number to check, in international or national format. Example: 32456789023

type string

The type of check to perform. Must be either HLR or Verify. Example: HLR

Introduction

Authenticating requests

Endpoints

List user's checks

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Query Parameters

Get check results (HLR or Verify)

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

URL Parameters

Create a new check (HLR or Verify)

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Body Parameters

Request

Request

Request