HomeAPI Documentation

Getting Started

The IP Company API allows you to identify the company behind any IP address. This guide will help you get started with our API in minutes.

Quick Start
Follow these steps to make your first API call
1

Get Your API Key

Sign up for a free account and get your API key from the dashboard, or generate a team API key under Team Settings.

2

Make Your First Request

Use the API key to authenticate and make a POST request to the lookup endpoint. No sign-up is required to try the demo endpoint first.

3

Process the Response

Parse the JSON response to access company data and your current credit balance.

Authentication

All API requests require authentication via an API key. Include your API key in the request body or as a query parameter. Two key types are supported.

API Key Types
Your key type is detected automatically from its prefix.
PrefixTypeScope
ipco_Personal (legacy)Auto-generated at signup, tied to your user account and monthly quota
pk_ / sk_Team keyCreated from Team Settings, tied to a team's shared credit pool
ipco_demo_74334eea-11a6-4dba-be58-7d2050a86f76
Never share your API key publicly or commit it to version control.
Personal accounts with a pending payment status receive a 402 response until checkout is completed. Admin accounts bypass this check.
Authentication Methods

Request Body (Recommended)

json
{
  "ip": "185.15.68.1",
  "apiKey": "ipco_demo_your_api_key_here"
}

Query Parameter

bash
curl "https://revealiq.io/api/stats?apiKey=ipco_demo_your_api_key_here"

Query-parameter auth is available on GET endpoints such as /api/stats. The /api/lookup POST endpoint requires the key in the JSON body.

Endpoints

POST/api/lookup
Identify the company behind an IP address. Deducts one credit only when a company record already exists for that IP.

Request

javascript
const response = await fetch('https://revealiq.io/api/lookup', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    ip: '185.15.68.1',
    apiKey: 'ipco_demo_your_api_key_here'
  })
});

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

Parameters

ParameterTypeRequiredDescription
ipstringYesIPv4 address to lookup
apiKeystringYesYour ipco_ personal key or pk_/sk_ team key

Behavior notes

  • If the IP is not yet in the database, it is queued for enrichment and a 404 is returned—no credit is deducted for misses.
  • Team keys draw from the team's shared credit pool; personal keys draw from your monthly quota or active subscription pack.
  • Requests are rate-limited per minute based on plan (see Rate Limits).
GET/api/lookup
Fetch a single stored IP record, or list stored records with pagination.

Request

bash
curl "https://revealiq.io/api/lookup?ip=185.15.68.1"

Parameters

ParameterTypeRequiredDescription
ipstringNoReturn a single record for this IP. Overrides pagination.
pagenumberNoPage number, default 1
limitnumberNoRecords per page, default 10
This endpoint currently does not require an API key.
POST/api/lookup/bulkBatch
Look up up to 50 IPv4 or IPv6 addresses in a single request. Only successful hits consume credits.

Request

bash
curl -X POST https://revealiq.io/api/lookup/bulk \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "ipco_demo_your_api_key_here",
    "ips": ["185.15.68.1", "142.250.185.78", "40.112.72.1"]
  }'

Parameters

ParameterTypeRequiredDescription
apiKeystringYesPersonal ipco_ key (team keys are not accepted on this endpoint)
ipsstring[]YesNon-empty array of IPv4/IPv6 addresses, max 50 per request, deduplicated automatically

Response

json
{
  "success": true,
  "results": [
    { "ip": "185.15.68.1", "found": true, "data": { "...": "..." } },
    { "ip": "142.250.185.78", "found": true, "data": { "...": "..." } }
  ],
  "summary": {
    "total": 2,
    "found": 2,
    "notFound": 0,
    "creditsUsed": 2
  },
  "credits": {
    "used": 152,
    "remaining": 848,
    "limit": 1000
  }
}
Rate-limited to 10 bulk requests per minute per account.
GET/api/stats
Get your account statistics, quota status, and recent lookup history

Request

bash
curl "https://revealiq.io/api/stats?apiKey=ipco_demo_your_api_key_here"

Alternatively, this endpoint accepts your dashboard session cookie—no apiKey is needed when calling it from a signed-in browser session. Team keys are not accepted here.

Response

json
{
  "success": true,
  "data": {
    "user": { "id": "...", "email": "...", "name": "...", "company": "...", "plan": "pro", "apiKey": "..." },
    "stats": {
      "totalRequests": 152,
      "successfulRequests": 140,
      "successRate": 92,
      "monthlyQuota": 5000,
      "usedQuota": 152,
      "remainingQuota": 4848,
      "quotaPeriodStart": "2026-08-01T00:00:00.000Z",
      "nextResetDate": "2026-09-01T00:00:00.000Z",
      "daysUntilReset": 8
    },
    "chartData": [
      { "date": "2026-08-18", "requests": 12 }
    ],
    "recentLookups": [
      { "ip": "185.15.68.1", "companyName": "L'Oreal S.A.", "success": true, "createdAt": "..." }
    ]
  }
}
POST/api/demo
Try the API without authentication (limited, rate-limited by client IP)

Request

javascript
const response = await fetch('https://revealiq.io/api/demo', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    ip: '142.250.185.78'
  })
});

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

Response

json
{
  "success": true,
  "identified": true,
  "data": {
    "ip": "142.250.185.78",
    "companyName": "Google LLC",
    "companyUrl": "https://google.com",
    "industry": "Technology",
    "employeeCount": "100,000+",
    "revenue": "$280B",
    "city": "Mountain View",
    "country": "United States",
    "isp": "Google LLC",
    "domain": "google.com",
    "customFields": []
  },
  "message": "Sign up for a free API key to get real-time lookups and webhooks.",
  "rateLimit": { "limit": 10, "used": 1, "remaining": 9 }
}

If the IP isn't recognized, identified is omitted and the response instead includes "pending": true. GET /api/demo returns a small set of sample IPs you can try immediately.

Demo endpoint is rate-limited to 10 requests per hour per client IP.

Response Format

All responses are returned in JSON format. A successful /api/lookupresponse includes the company data associated with the requested IP address, plus your current credit balance.

Success Response
json
{
  "success": true,
  "data": {
    "id": "clx1234567890",
    "ip": "185.15.68.1",
    "companyName": "L'Oreal S.A.",
    "companyUrl": "https://www.loreal.com",
    "companyLogo": "https://example.com/logo.png",
    "industry": "Cosmetics & Beauty",
    "employeeCount": "88,000+",
    "revenue": "38.26 billion EUR",
    "address": "14 Rue Royale",
    "city": "Paris",
    "postalCode": "75008",
    "country": "France",
    "isp": "Orange Business Services",
    "domain": "loreal.com",
    "status": "identified",
    "intentData": "{
  "buyingSignals": [
    "pricing_page_visit",
    "demo_request",
    "comparison_page_view"
  ],
  "engagementScore": 0.85,
  "topics": [
    "CRM software",
    "sales automation",
    "lead management"
  ],
  "lastActivity": "2024-01-15T10:30:00Z",
  "pageViews": 12,
  "timeOnSite": 420,
  "source": "website_tracking"
}",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "credits": {
    "used": 2548,
    "limit": 10000,
    "remaining": 7452,
    "source": "quota"
  }
}

credits.source is "team" when authenticated with a team key,"subscription" when drawing from an active credit pack, or"quota" for the default monthly allowance. intentData is a JSON-encoded string of buying-signal and engagement data; parse it withJSON.parse() before use, and expect null when no intent data has been collected for that record.

Error Codes

The API uses standard HTTP status codes to indicate the result of your request.

CodeNameDescription
400Bad RequestInvalid IP address, missing parameters, or malformed request body
401UnauthorizedMissing or invalid API key
402Payment RequiredAccount payment is pending; complete checkout to use the API (personal keys only)
403ForbiddenTeam role does not have API access permission
404Not FoundIP address not found in database (queued for enrichment, no credit deducted)
429Too Many RequestsPer-minute rate limit or credit/quota limit exceeded
500Internal Server ErrorAn unexpected error occurred
Error Response Format
Generic Error
json
{
  "error": "Invalid IP address format"
}
IP Not Found (404)
json
{
  "success": false,
  "error": "IP not found in database",
  "message": "IP has been saved for future enrichment.",
  "data": null,
  "credits": { "used": 153, "limit": 10000, "remaining": 9847, "source": "quota" }
}
Payment Pending (402)
json
{
  "error": "Account payment is pending. Please complete checkout to use the API.",
  "paymentPending": true
}
Rate Limited (429)
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again after 42 seconds.",
  "retryAfter": 42
}

Rate Limits & Quotas

Two independent limits apply: a per-minute request rate limit on /api/lookup, and a monthly credit quota that only decrements on successful lookups.

PlanMonthly CreditsRate Limit
Free100 requests10 requests/minute
Starter1,000 credits100 requests/minute
Professional5,000 credits500 requests/minute
Enterprise25,000 credits2,000 requests/minute

/api/lookup/bulk has a separate limit of 10 requests per minute (up to 50 IPs per request). /api/demo is limited to 10 requests per hour per client IP and does not require a key.