This quickstart gets you from zero → first successful lookup with the IRBIS API:
- Create an API key
- Fetch your available
lookupIdvalues - Submit a lookup request (Phone example)
- Retrieve results using the returned request
id - Verify your credit status
Note: Many IRBIS lookups are asynchronous. The first response typically returns
status: "progress" and a numeric id. You then retrieve the completed results using the api-usage/{id} endpoint.
1
Prerequisites
You need:
- An IRBIS account
- An API key (generated in the IRBIS portal)
2
Create your API key (Portal)
- Register: https://irbis.espysys.com/auth/register
- Open API Keys page: https://irbis.espysys.com/developer
- Click "Generate API key" (upper-left), then copy the key
Keep your key secret. Use it server-side.
3
Fetch your available lookup IDs (Required)
IRBIS endpoints require a lookupId that matches what's enabled for your subscription. Call lookupid-list and choose the right ID for the service you want.
Endpoint
GET
https://irbis.espysys.com/api/request-monitor/lookupid-list?key={API_KEY}
cURL
lookupid-list.sh
# Fetch your available lookup IDs curl -X 'GET' \ 'https://irbis.espysys.com/api/request-monitor/lookupid-list?key=YOUR_API_KEY' \ -H 'accept: application/json' \ -H 'Content-Type: application/json'
What you get back
A JSON array with objects like:
| Field | Type | Description |
|---|---|---|
| lookupId | integer | The ID to use in your lookup requests |
| endPoint | string | API path this ID corresponds to |
| lookupName | string | Human-friendly name of the lookup type |
Pick the lookupId for
"/api/developer/combined_phone" → Phone Lookup (Combo)"/api/developer/combined_email" → Email Lookup (Combo)"/api/developer/combined_name" → Name SocialScan/WebScan (Combo)4
Make your first API call (Phone Lookup example)
Endpoint
POST
https://irbis.espysys.com/api/developer/combined_phone
Headers
headers
Content-Type: application/json
Body
| Field | Type | Description |
|---|---|---|
| key | string | Your API key |
| value | string | Phone number to look up |
| lookupId | integer | The lookupId you selected for Phone Lookup |
cURL
phone-lookup.sh
curl -X 'POST' \ 'https://irbis.espysys.com/api/developer/combined_phone' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "key": "<API_Key>", "value": "+79017007397", "lookupId": <LOOKUPID_VALUE> }'
Typical response
You'll receive an id and status: "progress". Save the numeric id and retrieve the completed data using the results endpoint.
response.json
{
"requestId": "5d60f1b7-e614-4524-bce6-174a81a2fd90",
"id": 1486,
"status": "progress",
"message": "Results will be available soon, Use API to retrieve Data"
}
✅ Save the numeric
id — you'll use it in the next step.
5
Retrieve the results (api-usage/{id})
Endpoint
GET
https://irbis.espysys.com/api/request-monitor/api-usage/{id}?key={API key}
cURL
get-results.sh
curl -X 'GET' \ 'https://irbis.espysys.com/api/request-monitor/api-usage/<RESPONSE_ID_VALUE>?key=<API_Key>' \ -H 'accept: application/json'
Polling guidance
If the request is still processing, wait and try again. Use a simple backoff (e.g.,
2s → 5s → 10s) rather than tight loops.
6
Check your credits balance (credit-stat)
Endpoint
GET
https://irbis.espysys.com/api/request-monitor/credit-stat?key=YOUR_API_KEY
cURL
credit-stat.sh
curl -X 'GET' \ 'https://irbis.espysys.com/api/request-monitor/credit-stat?key=YOUR_API_KEY' \ -H 'accept: application/json' \ -H 'Content-Type: application/json'
Response fields
| Field | Description |
|---|---|
| balance | Current credit balance |
| currency | Currency of the balance |
| credits | Number of credits remaining |
| expiratioDate | Date when credits expire |
| status | Account status |
7
Important limits and common errors
"Insufficient enrichment timeout"
IRBIS enforces a 30-second timeout between searches. If you call too fast, you may get an error like "Insufficient enrichment timeout". Wait at least 30 seconds between searches (or consider a Custom package if you need a shorter timeout).
Wrong
lookupIdIf your request fails or returns unexpected behavior, confirm the lookupId via:
GET
/api/request-monitor/lookupid-list?key=...
Still "progress"
That's expected. Use:
GET
/api/request-monitor/api-usage/{id}?key=...