IllyVoIPdevelopers

Number Lookup & HLR

Live HLR lookup

Returns operator, portability, current-network, and active-status intelligence.

Try in API Playground ↗Sign in to prepare and run this request.
POST/api/v1/lookup/hlr

Before you start

Use a complete number and choose only the optional checks you need. This is a paid live lookup.

Result

Read the returned status and cost_eur. Availability of extra activity or porting information depends on the number.

Charges and safe retries

A repeated live lookup is another request and may incur another charge.

Authentication

Send your account API key in the X-Api-Key header. Keep it on your server; never embed it in browser code.

Request examples

Replace the example values with your own inputs. Examples do not run on this page. Production requests can change your account or incur charges.

cURL

cURL
curl -X POST "https://api.illyvoip.com/api/v1/lookup/hlr" \
  -H "X-Api-Key: ${ILLYVOIP_API_KEY:?Set ILLYVOIP_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "YOUR_PHONE_NUMBER",
    "include_ported_date": true
}'

Node.js

Node.js
const response = await fetch("https://api.illyvoip.com/api/v1/lookup/hlr", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.ILLYVOIP_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "number": "YOUR_PHONE_NUMBER",
    "include_ported_date": true
})
});

const data = await response.json();
console.log(response.status, data);

PHP

PHP
<?php
$ch = curl_init('https://api.illyvoip.com/api/v1/lookup/hlr');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('ILLYVOIP_API_KEY'),
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => '{
    "number": "YOUR_PHONE_NUMBER",
    "include_ported_date": true
}',
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response;

Python

Python
import os
import json
import requests

response = requests.request(
    "POST",
    "https://api.illyvoip.com/api/v1/lookup/hlr",
    headers={
        "X-Api-Key": os.environ["ILLYVOIP_API_KEY"],
        'Content-Type': 'application/json'
    },
    json=json.loads("{\n    \"number\": \"YOUR_PHONE_NUMBER\",\n    \"include_ported_date\": true\n}"),
)

print(response.status_code)
print(response.json())

Node.js examples run on the server (Node.js 22.17+). Python examples require requests; PHP examples require cURL. Set the environment variables referenced in each example.

Request body

application/json

Body required.

numberstringrequired

Phone number in international format.

include_ported_datebooleanoptional

Requests the ported date when the operator supports it. If a ported date is returned, the billed total is €0.0200. If a ported date is unavailable, the lookup stays at its normal base cost.

check_landline_activitybooleanoptional

Requests live activity checks for supported UK and Ireland fixed-line numbers. When the number qualifies, the billed total is €0.0120. Other numbers stay at their normal base cost.

check_us_mobile_activitybooleanoptional

Requests the deeper live activity check used for supported United States mobile numbers. When the number qualifies, the billed total is €0.0150. Non-US or non-mobile numbers stay at their normal base cost.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "number": {
      "type": "string",
      "description": "Phone number in international format."
    },
    "include_ported_date": {
      "type": "boolean",
      "description": "Requests the ported date when the operator supports it. If a ported date is returned, the billed total is €0.0200. If a ported date is unavailable, the lookup stays at its normal base cost."
    },
    "check_landline_activity": {
      "type": "boolean",
      "description": "Requests live activity checks for supported UK and Ireland fixed-line numbers. When the number qualifies, the billed total is €0.0120. Other numbers stay at their normal base cost."
    },
    "check_us_mobile_activity": {
      "type": "boolean",
      "description": "Requests the deeper live activity check used for supported United States mobile numbers. When the number qualifies, the billed total is €0.0150. Non-US or non-mobile numbers stay at their normal base cost."
    }
  },
  "required": [
    "number"
  ]
}
Example body
JSON
{
  "number": "+447700900123",
  "include_ported_date": true
}

Request behavior

This is a billed HLR lookup product. With the current pricing, a standard live lookup is €0.0100. A returned ported date makes the billed total €0.0200. Supported UK/Ireland fixed-line activity checks bill €0.0120 total, supported US mobile activity checks bill €0.0150 total, and a supported US mobile lookup that also returns a ported date bills €0.0250. The response returns the exact billed amount in cost_eur, identifies result_source as live or cached, supplies result_fetched_at, and keeps replayed as the separate duplicate-response fact.

Conditions and examples

Duplicate-charge protection: enabled.

Response fields

  • status: Request outcome. Read the resource state separately; success does not always mean delivery or completion.
  • lookup: Normalized number and the requested number information; missing optional fields are not proof of inactivity.
  • cost_eur: Amount billed for this request, in EUR.
  • result_source: Whether the lookup result came from the documented lookup mode.
  • result_fetched_at: Time the lookup information was obtained.
  • replayed: Whether this response reuses an earlier request with the same idempotency key.

HTTP responses

Expand a status to inspect its documented response format and examples. Example prices, IDs and timestamps are illustrative values, not quotes or account records.

200 Successful customer-facing response.

application/json

JSON
{
  "status": "success",
  "lookup": {
    "lookup_id": "HLR-91A7B4C26D03",
    "requested_number": "+447700900123",
    "detected_number": "447700900123",
    "formatted_number": "+44 7700 900123",
    "number_type": "Mobile",
    "number_status": "active",
    "ported_number": true,
    "ported_on": "2024-11-01",
    "current_network": {
      "name": "Telefonica UK (Virgin Media O2)",
      "country_name": "United Kingdom",
      "country_prefix": "44",
      "mccmnc": "23410"
    },
    "original_network": {
      "name": "VODAFONE LIMITED",
      "country_name": "United Kingdom",
      "country_prefix": "44",
      "mccmnc": "23415"
    }
  },
  "cost_eur": 0.02,
  "result_source": "live",
  "result_fetched_at": "2026-08-31T12:34:56+00:00",
  "replayed": false
}
statusstringrequired
enum ["success"]
lookupobjectrequired
View nested fields
lookup_idstringrequired
requested_numberstringrequired
detected_numberstringrequired
formatted_numberstringrequired
number_typestringrequired
number_statusstringrequired
ported_numberbooleanrequired
ported_onstringrequired
current_networkobjectrequired
View nested fields
namestringrequired
country_namestringrequired
country_prefixstringrequired
mccmncstringrequired

Additional properties: not allowed.

original_networkobjectrequired
View nested fields
namestringrequired
country_namestringrequired
country_prefixstringrequired
mccmncstringrequired

Additional properties: not allowed.

Additional properties: not allowed.

cost_eurnumberrequired
result_sourcestringrequired
result_fetched_atstringrequired
replayedbooleanrequired

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success"
      ]
    },
    "lookup": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "lookup_id": {
          "type": "string"
        },
        "requested_number": {
          "type": "string"
        },
        "detected_number": {
          "type": "string"
        },
        "formatted_number": {
          "type": "string"
        },
        "number_type": {
          "type": "string"
        },
        "number_status": {
          "type": "string"
        },
        "ported_number": {
          "type": "boolean"
        },
        "ported_on": {
          "type": "string"
        },
        "current_network": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string"
            },
            "country_name": {
              "type": "string"
            },
            "country_prefix": {
              "type": "string"
            },
            "mccmnc": {
              "type": "string"
            }
          },
          "required": [
            "name",
            "country_name",
            "country_prefix",
            "mccmnc"
          ]
        },
        "original_network": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string"
            },
            "country_name": {
              "type": "string"
            },
            "country_prefix": {
              "type": "string"
            },
            "mccmnc": {
              "type": "string"
            }
          },
          "required": [
            "name",
            "country_name",
            "country_prefix",
            "mccmnc"
          ]
        }
      },
      "required": [
        "lookup_id",
        "requested_number",
        "detected_number",
        "formatted_number",
        "number_type",
        "number_status",
        "ported_number",
        "ported_on",
        "current_network",
        "original_network"
      ]
    },
    "cost_eur": {
      "type": "number"
    },
    "result_source": {
      "type": "string"
    },
    "result_fetched_at": {
      "type": "string"
    },
    "replayed": {
      "type": "boolean"
    }
  },
  "required": [
    "status",
    "lookup",
    "cost_eur",
    "result_source",
    "result_fetched_at",
    "replayed"
  ]
}
400 The request failed validation.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
401 The API key or browser token is missing or invalid.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
402 The account has insufficient available credit.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
403 The account is not allowed to perform this operation.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
409 The request conflicts with the current resource or operation state.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
429 The request rate limit was exceeded.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
500 An unexpected service error occurred.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
503 The service is temporarily unavailable.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}

Sandbox scenarios

Use https://sandbox-api.illyvoip.com with Sandbox credentials and the X-Illyvoip-Sandbox-Scenario header. Omit the header for the documented success default. This header belongs to sandbox requests.

success, not-found, rate-limited, forbidden, service-unavailable, unknown, ported, unavailable, insufficient-credit

Try this operation in Sandbox · Environment setup and limitations

Look up phone number

Search API operations, parameters, SDK and webhooks.