> ## Documentation Index > Fetch the complete documentation index at: https://docs.leadpipe.com/llms.txt > Use this file to discover all available pages before exploring further. # Get IP2Company lookup > Read a saved IP2Company result or poll accepted enrichment. ISP-classified results are free; inspect freshness and refreshStatus before treating saved data as a finished refresh. See [IP2Company lookup, polling, and credits](https://docs.leadpipe.com/ip-to-company/introduction.md) for request examples and how to interpret ISP data, freshness, reservations, and errors. ## OpenAPI ````yaml /ip-to-company/openapi.json get /v1/lookup openapi: 3.1.0 info: title: IP2Company API version: 1.0.0 description: >- Look up or enrich an IP-to-company association and track dedicated IP2Company credits. Authenticate with your Leadpipe organization API key in X-API-Key. servers: - url: https://company.leadpipe.com description: Leadpipe production security: - apiKeyAuth: [] tags: - name: Visitors description: Visitor resources and privacy-bounded activity. - name: Usage description: Organization usage and billing-period consumption. paths: /v1/lookup: get: tags: - Visitors summary: Get IP2Company lookup description: >- Looks up one IP using the authenticated Leadpipe API key and its organization. Requires IP2Company API permission. These credits are independent of people, Company Visitors and intent allowances. ISP-classified results retain all available data and consume zero credits, even when named or stale. Completed company, unclassified and no-company responses consume one credit, including repeated-IP and stale responses. An explicit company match on an ISP network is classified company and remains chargeable. Paid completions recheck the balance before returning data. Saved ISP results remain readable at zero balance. POST reserves one credit per organization/IP before requesting enrichment; duplicate pending submissions reuse the hold. With no available credit and no existing hold, POST may only read an already saved ISP result, without starting a refresh; other results return 429. A fresh final ISP response releases its hold without a debit. A saved ISP response with stale data or pending/deferred refresh keeps the hold until enrichment finishes; inspect refreshStatus, pollAfterSeconds and reserved, including on HTTP 200. Pending, missing and failed requests are recorded without a debit. Pending and uncertain/rejected submissions retain their hold for retrying that IP; no automatic cancellation or expiry is implied. Every organization key shares the billing-period balance. remaining excludes reservations, which survive billing resets and remain visible separately. Results describe an inferred company association and may be stale; they do not prove employment or IP ownership. No person, form-email or website-visit details are returned. There is no additional application request-rate ceiling: service admission, pending-enrichment and provider capacity still apply. Honor Retry-After; clients must not blindly retry completed paid responses or an uncertain accounting failure. Responses must not be cached or prefetched. GET reads saved data or polls an accepted enrichment; it never submits a new IP. A missing result returns status missing and data null, which is not a definitive no-company result. operationId: getIp2companyLookup parameters: - schema: type: string maxLength: 64 description: One IPv4 or IPv6 address. URLs, CIDRs and ports are rejected. example: 192.0.2.10 required: true description: One IPv4 or IPv6 address. URLs, CIDRs and ports are rejected. name: ip in: query example: 192.0.2.10 responses: '200': description: >- Saved or missing lookup with current credit balance; ISP data is free and may include a pending refresh. headers: Retry-After: description: >- Minimum seconds before polling pending work or retrying a deferred refresh; can also accompany saved data with HTTP 200. schema: type: integer minimum: 1 content: application/json: schema: type: object properties: ip: type: string status: type: string enum: - complete - pending - missing data: type: - object - 'null' properties: ip: type: string description: Normalized IP address that was looked up. businessCategory: type: string description: >- Provider audience classification; empty when unavailable. businessSegment: type: string description: Provider audience segment; empty when unavailable. dataCompleteness: type: string description: >- Provider detail classification, not a computed completeness score; empty when unavailable. isInternetProvider: type: - boolean - 'null' description: >- Whether the provider identifies the network connection as an ISP; null when unknown. Can be true when classification is company. accessType: type: string description: >- Provider network access classification; empty when unavailable. classification: type: string enum: - company - isp - unclassified_organization - no_company_found description: >- Company association classification. An explicit provider company match can identify a business on an ISP connection; isInternetProvider and accessType still describe the network. Without explicit match evidence, company requires identity, corporate access and non-ISP status. name: type: string description: >- Company name; can be empty if only a company identifier was supplied. website: type: string description: Company website or domain; empty when unavailable. tradeName: type: string description: >- Company marketing name, not necessarily a registered trade name; empty when unavailable. industry: type: string description: Company industry; empty when unavailable. subIndustry: type: string description: Company sub-industry; empty when unavailable. linkedinUrl: type: - string - 'null' description: >- Company LinkedIn profile URL, or null when unavailable. employeeCount: type: - integer - 'null' minimum: 0 maximum: 9007199254740991 description: >- Provider-reported employee count, or null when unavailable. annualSales: type: - integer - 'null' minimum: 0 maximum: 9007199254740991 description: >- Provider-reported annual sales amount, or null when unavailable; currency is not supplied by the source. revenueRange: type: string description: Provider revenue range; empty when unavailable. primaryNaics: type: string description: >- Primary NAICS code, retained as text; empty when unavailable. primarySic: type: string description: >- Primary SIC code, retained as text; empty when unavailable. city: type: string description: Company city; empty when unavailable. state: type: string description: Company state or region; empty when unavailable. postalCode: type: string description: Company postal code; empty when unavailable. countryCode: type: string description: Company country code; empty when unavailable. countryName: type: string description: Company country name; empty when unavailable. required: - ip - businessCategory - businessSegment - dataCompleteness - isInternetProvider - accessType - classification - name - website - tradeName - industry - subIndustry - linkedinUrl - employeeCount - annualSales - revenueRange - primaryNaics - primarySic - city - state - postalCode - countryCode - countryName stale: type: - boolean - 'null' pollAfterSeconds: type: - integer - 'null' minimum: 0 refreshStatus: type: - string - 'null' enum: - not_needed - not_requested - pending - deferred - null description: >- Refresh state for saved data, including HTTP 200 responses. pending confirms accepted unfinished work; deferred requires retrying POST after pollAfterSeconds; not_requested means this read started no refresh; not_needed means no refresh is required. Null without saved data. stale independently describes the saved result age. meta: type: object properties: enabled: type: boolean limit: type: integer minimum: 0 used: type: integer minimum: 0 reserved: type: integer minimum: 0 remaining: type: integer minimum: 0 periodStart: type: string format: date-time creditsConsumed: anyOf: - type: number enum: - 0 - type: number enum: - 1 description: >- Zero for ISP-classified results, including named and stale ISP results, and for pending/missing/failed work. Completed company, unclassified and no-company results consume one credit. A company match on an ISP network is classified company and remains chargeable. required: - enabled - limit - used - reserved - remaining - periodStart - creditsConsumed required: - ip - status - data - stale - pollAfterSeconds - refreshStatus - meta example: ip: 192.0.2.10 status: missing data: null stale: null pollAfterSeconds: null refreshStatus: null meta: enabled: true limit: 10000 used: 0 reserved: 1 remaining: 9999 periodStart: '2026-11-12T00:00:00.000Z' creditsConsumed: 0 '202': description: Acknowledged enrichment is pending; poll GET. headers: Retry-After: description: >- Minimum seconds before polling pending work or retrying a deferred refresh; can also accompany saved data with HTTP 200. schema: type: integer minimum: 1 content: application/json: schema: type: object properties: ip: type: string status: type: string enum: - complete - pending - missing data: type: - object - 'null' properties: ip: type: string description: Normalized IP address that was looked up. businessCategory: type: string description: >- Provider audience classification; empty when unavailable. businessSegment: type: string description: Provider audience segment; empty when unavailable. dataCompleteness: type: string description: >- Provider detail classification, not a computed completeness score; empty when unavailable. isInternetProvider: type: - boolean - 'null' description: >- Whether the provider identifies the network connection as an ISP; null when unknown. Can be true when classification is company. accessType: type: string description: >- Provider network access classification; empty when unavailable. classification: type: string enum: - company - isp - unclassified_organization - no_company_found description: >- Company association classification. An explicit provider company match can identify a business on an ISP connection; isInternetProvider and accessType still describe the network. Without explicit match evidence, company requires identity, corporate access and non-ISP status. name: type: string description: >- Company name; can be empty if only a company identifier was supplied. website: type: string description: Company website or domain; empty when unavailable. tradeName: type: string description: >- Company marketing name, not necessarily a registered trade name; empty when unavailable. industry: type: string description: Company industry; empty when unavailable. subIndustry: type: string description: Company sub-industry; empty when unavailable. linkedinUrl: type: - string - 'null' description: >- Company LinkedIn profile URL, or null when unavailable. employeeCount: type: - integer - 'null' minimum: 0 maximum: 9007199254740991 description: >- Provider-reported employee count, or null when unavailable. annualSales: type: - integer - 'null' minimum: 0 maximum: 9007199254740991 description: >- Provider-reported annual sales amount, or null when unavailable; currency is not supplied by the source. revenueRange: type: string description: Provider revenue range; empty when unavailable. primaryNaics: type: string description: >- Primary NAICS code, retained as text; empty when unavailable. primarySic: type: string description: >- Primary SIC code, retained as text; empty when unavailable. city: type: string description: Company city; empty when unavailable. state: type: string description: Company state or region; empty when unavailable. postalCode: type: string description: Company postal code; empty when unavailable. countryCode: type: string description: Company country code; empty when unavailable. countryName: type: string description: Company country name; empty when unavailable. required: - ip - businessCategory - businessSegment - dataCompleteness - isInternetProvider - accessType - classification - name - website - tradeName - industry - subIndustry - linkedinUrl - employeeCount - annualSales - revenueRange - primaryNaics - primarySic - city - state - postalCode - countryCode - countryName stale: type: - boolean - 'null' pollAfterSeconds: type: - integer - 'null' minimum: 0 refreshStatus: type: - string - 'null' enum: - not_needed - not_requested - pending - deferred - null description: >- Refresh state for saved data, including HTTP 200 responses. pending confirms accepted unfinished work; deferred requires retrying POST after pollAfterSeconds; not_requested means this read started no refresh; not_needed means no refresh is required. Null without saved data. stale independently describes the saved result age. meta: type: object properties: enabled: type: boolean limit: type: integer minimum: 0 used: type: integer minimum: 0 reserved: type: integer minimum: 0 remaining: type: integer minimum: 0 periodStart: type: string format: date-time creditsConsumed: anyOf: - type: number enum: - 0 - type: number enum: - 1 description: >- Zero for ISP-classified results, including named and stale ISP results, and for pending/missing/failed work. Completed company, unclassified and no-company results consume one credit. A company match on an ISP network is classified company and remains chargeable. required: - enabled - limit - used - reserved - remaining - periodStart - creditsConsumed required: - ip - status - data - stale - pollAfterSeconds - refreshStatus - meta example: ip: 192.0.2.10 status: pending data: null stale: null pollAfterSeconds: 15 refreshStatus: null meta: enabled: true limit: 10000 used: 0 reserved: 1 remaining: 9999 periodStart: '2026-11-12T00:00:00.000Z' creditsConsumed: 0 '400': description: Invalid IP, identifier or usage range. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string details: {} required: - code - message meta: type: object properties: timestamp: type: string format: date-time request_id: type: string required: - timestamp - request_id required: - error - meta example: error: code: HTTP_ERROR message: Invalid request meta: timestamp: '2026-11-12T00:00:00.000Z' request_id: 11111111-1111-4111-8111-111111111111 '401': description: >- A valid Leadpipe API key or the documented dashboard authentication is required. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string details: {} required: - code - message meta: type: object properties: timestamp: type: string format: date-time request_id: type: string required: - timestamp - request_id required: - error - meta example: error: code: HTTP_ERROR message: Missing X-API-Key header meta: timestamp: '2026-11-12T00:00:00.000Z' request_id: 11111111-1111-4111-8111-111111111111 '403': description: The key, organization or feature is not eligible. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string details: {} required: - code - message meta: type: object properties: timestamp: type: string format: date-time request_id: type: string required: - timestamp - request_id required: - error - meta example: error: code: HTTP_ERROR message: IP2Company API access is disabled meta: timestamp: '2026-11-12T00:00:00.000Z' request_id: 11111111-1111-4111-8111-111111111111 '405': description: HEAD cannot perform a lookup or consume credits. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string details: {} required: - code - message meta: type: object properties: timestamp: type: string format: date-time request_id: type: string required: - timestamp - request_id required: - error - meta example: error: code: HTTP_ERROR message: Use GET or POST for IP2Company lookups meta: timestamp: '2026-11-12T00:00:00.000Z' request_id: 11111111-1111-4111-8111-111111111111 '429': description: >- IP2Company credits exhausted or service admission capacity reached. Retry-After is emitted only for temporary service limits. headers: Retry-After: description: >- Minimum seconds before retrying a temporary capacity limit; absent for credit exhaustion. schema: type: integer minimum: 1 content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string details: {} required: - code - message meta: type: object properties: timestamp: type: string format: date-time request_id: type: string required: - timestamp - request_id required: - error - meta example: error: code: HTTP_ERROR message: IP2Company credit allowance exhausted meta: timestamp: '2026-11-12T00:00:00.000Z' request_id: 11111111-1111-4111-8111-111111111111 '503': description: >- Lookup or durable accounting is unavailable. An uncertain accounting result must not be retried automatically. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string details: {} required: - code - message meta: type: object properties: timestamp: type: string format: date-time request_id: type: string required: - timestamp - request_id required: - error - meta example: error: code: HTTP_ERROR message: IP2Company temporarily unavailable meta: timestamp: '2026-11-12T00:00:00.000Z' request_id: 11111111-1111-4111-8111-111111111111 security: - apiKeyAuth: [] components: securitySchemes: apiKeyAuth: type: apiKey in: header name: X-API-Key description: >- Organization API key (sk_...). Get yours from Settings > API Keys in the dashboard. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.