{ "openapi": "3.0.4", "info": { "title": "Elioplus IP Company API", "description": "The **Elioplus IP Company API** infers company firmographics from an IP address.\nGiven an IPv4 or IPv6 address, it returns the most likely company behind that IP,\ntogether with a **confidence score** so you can decide how to use each result.\n\nResults are probabilistic inferences derived from third-party signals. They are\n**not** guaranteed statements of identity or ownership — always consider the\nconfidence score and status before acting on a result.\n\n## Authentication\n\nAll endpoints (except `GET /v1/metadata`) require an API key sent as a Bearer token:\n\n```http\nAuthorization: Bearer \n```\n\n- Manage your keys from the Elioplus dashboard.\n- **Never** send API keys in the query string — such requests are rejected with `invalid_request`.\n- Treat keys as secrets: do not embed them in client-side code or public repositories.\n\n## Confidence & match status\n\nEvery lookup returns a `confidence` object and a `status`.\n\nThe `confidence.score` is an integer from **0 to 100**. The `confidence.level` summarises it:\n\n| Level | Score | What it means |\n|--------------|---------|----------------------------------------------------------|\n| `high` | 85–100 | Strong match — safe to use with minimal review. |\n| `medium` | 60–84 | Likely match — good for most use cases. |\n| `low` | 35–59 | Weak match — verify before relying on it. |\n| `not_found` | 0–34 | No reliable company could be identified. |\n\nThe `status` field describes the outcome of the lookup:\n\n| Status | Meaning |\n|----------------------------|---------------------------------------------------------------------|\n| `matched` | A company was identified with medium-or-higher confidence. |\n| `low_confidence` | A candidate company was found, but confidence is low. |\n| `not_found` | No company could be associated with the IP. |\n| `rejected_isp_or_hosting` | The IP belongs to an ISP, hosting provider, or data center — not a company. |\n| `provider_unavailable` | An upstream data source was temporarily unavailable; retry later. |\n\n> Scores are relative indicators of match quality, not statistical probabilities.\n> The exact scoring method is proprietary and may change without notice; treat the\n> `level` bands above as the stable contract.\n\n## Rate limits\n\nRequests are rate limited **per API key** using a fixed one-minute window. The default\nceiling is **120 requests per minute**; your effective limit may differ by plan and is\nalways reported in the response headers below.\n\n| Header | Description |\n|-------------------------|-------------------------------------------------------------------|\n| `X-RateLimit-Limit` | Maximum requests allowed in the current window. |\n| `X-RateLimit-Remaining` | Requests remaining in the current window. |\n| `X-RateLimit-Reset` | Unix timestamp (seconds) when the window resets. |\n| `Retry-After` | Seconds to wait before retrying (sent on `429` responses). |\n\nExceeding the limit returns **`429 Too Many Requests`** with error code `rate_limited`.\nBack off until the window resets, and honour `Retry-After` when present.\n\n## Credits & usage\n\n- Each **successful** lookup consumes **one credit**. Failed lookups (e.g. validation\n errors, provider outages) do not consume credits.\n- New accounts include a trial allowance of **50 calls**.\n- When your monthly credits are exhausted, lookups return `429` with error code\n `quota_exceeded`.\n- Check your balance at any time with `GET /v1/account/credits`, and review historical\n usage with `GET /v1/account/usage`.\n\n### Idempotency\n\nSend an optional `Idempotency-Key` header to make retries safe. Reusing a key that was\nalready processed returns **`409 Conflict`** (`idempotency_key_reused`) instead of\ncharging an additional credit.\n\n## Errors\n\nErrors use standard HTTP status codes and a consistent JSON body:\n\n```json\n{\n \"requestId\": \"b1e2...\",\n \"error\": {\n \"code\": \"invalid_ip\",\n \"message\": \"The provided IP address is not valid.\",\n \"documentationUrl\": \"https://api-companies.elioplus.com/docs/errors/invalid_ip\"\n }\n}\n```\n\n| Code | HTTP | Meaning |\n|--------------------------|------|----------------------------------------------------------------|\n| `invalid_request` | 400 | Malformed request (e.g. API key sent in the query string). |\n| `invalid_ip` | 400 | The `ip` value is not a valid IPv4/IPv6 address. |\n| `missing_api_key` | 401 | No API key was provided in the Authorization header. |\n| `invalid_api_key` | 401 | The API key is invalid, expired, or lacks the required scope. |\n| `payment_required` | 402 | No active Public Company API plan for this account. |\n| `api_key_revoked` | 403 | The API key has been revoked. |\n| `idempotency_key_reused` | 409 | The supplied `Idempotency-Key` was already used. |\n| `quota_exceeded` | 429 | Monthly credit allowance is exhausted. |\n| `rate_limited` | 429 | Too many requests in the current window. |\n| `internal_error` | 500 | Unexpected server error — retry, then contact support. |\n| `provider_unavailable` | 502 | An upstream data provider was temporarily unavailable. |\n\nEvery response includes an `X-Request-Id` header (also echoed as `requestId` in error\nbodies). Include it when contacting support so we can trace your request.", "version": "v1" }, "paths": { "/v1/account/credits": { "get": { "tags": [ "Public Company API" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditBalanceResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCompanyApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCompanyApiErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCompanyApiErrorResponse" } } } } } } }, "/v1/account/usage": { "get": { "tags": [ "Public Company API" ], "parameters": [ { "name": "months", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 6 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MonthlyUsageResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCompanyApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCompanyApiErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCompanyApiErrorResponse" } } } } } } }, "/v1/company-lookup": { "post": { "tags": [ "Public Company API" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicCompanyLookupHttpRequest" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCompanyApiResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCompanyApiErrorResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCompanyApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCompanyApiErrorResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCompanyApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCompanyApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCompanyApiErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCompanyApiErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCompanyApiErrorResponse" } } } } } } }, "/v1/metadata": { "get": { "tags": [ "Public Company API" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCompaniesMetadataResponse" } } } } } } } }, "components": { "schemas": { "CreditBalanceResponse": { "type": "object", "properties": { "creditsRemaining": { "type": "integer", "format": "int32" }, "periodEndsAt": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false }, "MonthlyUsageResponse": { "type": "object", "properties": { "Month": { "type": "string", "nullable": true }, "Calls": { "type": "integer", "format": "int32" }, "SuccessfulCalls": { "type": "integer", "format": "int32" }, "FailedCalls": { "type": "integer", "format": "int32" }, "CreditsConsumed": { "type": "integer", "format": "int32" }, "PeriodStartUtc": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "PublicCompaniesMetadataResponse": { "type": "object", "properties": { "Product": { "type": "string", "nullable": true }, "Version": { "type": "string", "nullable": true }, "DocsUrl": { "type": "string", "nullable": true }, "TrialCalls": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "PublicCompanyApiError": { "type": "object", "properties": { "code": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "documentationUrl": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PublicCompanyApiErrorResponse": { "type": "object", "properties": { "requestId": { "type": "string", "nullable": true }, "error": { "allOf": [ { "$ref": "#/components/schemas/PublicCompanyApiError" } ], "nullable": true } }, "additionalProperties": false }, "PublicCompanyApiResponse": { "type": "object", "properties": { "requestId": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "confidence": { "allOf": [ { "$ref": "#/components/schemas/PublicCompanyConfidence" } ], "nullable": true }, "usage": { "allOf": [ { "$ref": "#/components/schemas/PublicCompanyUsage" } ], "nullable": true }, "company": { "allOf": [ { "$ref": "#/components/schemas/PublicCompanyData" } ], "nullable": true }, "ipLocation": { "allOf": [ { "$ref": "#/components/schemas/PublicCompanyIpLocation" } ], "nullable": true } }, "additionalProperties": false }, "PublicCompanyConfidence": { "type": "object", "properties": { "level": { "type": "string", "nullable": true }, "score": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "PublicCompanyData": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "industry": { "type": "string", "nullable": true }, "employees": { "type": "string", "nullable": true }, "linkedin": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true }, "phoneNumber": { "type": "string", "nullable": true }, "revenue": { "type": "string", "nullable": true }, "yearFounded": { "type": "integer", "format": "int32", "nullable": true }, "facebook": { "type": "string", "nullable": true }, "twitter": { "type": "string", "nullable": true }, "instagram": { "type": "string", "nullable": true }, "youtube": { "type": "string", "nullable": true }, "angellist": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PublicCompanyIpLocation": { "type": "object", "properties": { "city": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PublicCompanyLookupHttpRequest": { "type": "object", "properties": { "ip": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PublicCompanyUsage": { "type": "object", "properties": { "creditsConsumed": { "type": "integer", "format": "int32" }, "creditsRemaining": { "type": "integer", "format": "int32" }, "periodEndsAt": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false } }, "securitySchemes": { "Bearer": { "type": "http", "description": "Use Authorization: Bearer . Never send Public Company API keys in query strings.", "scheme": "Bearer", "bearerFormat": "API key" } } }, "security": [ { "Bearer": [ ] } ], "tags": [ { "name": "Public Company API" } ] }