Company Search API

Search for companies worldwide and retrieve detailed corporate information including officers, owners, filings, and industry codes. No entity required - search by company name and jurisdiction.

Key Features

  • Standalone search - No entity required, search by name and jurisdiction directly
  • Real-time results - Synchronous responses (no webhooks needed)

Typical Workflow

  1. Search: POST company name and jurisdiction → Get list of matching companies
  2. Select: User selects correct company from results
  3. Details: GET detailed info using company ID → Get full profile

Search Response Object

The search response contains a list of matching companies with basic information. Use the company ID to retrieve full details.

Response Attributes

Field Type Description
items array List of matching companies (see Company Item below)
totalItems integer Total number of results returned
cached boolean Whether results were returned from cache (true = no charge)
cached_at datetime When results were cached (only present if cached=true)
hit_count integer Number of times this cached result has been accessed

Company Item Attributes

Field Type Description
id string Company ID (use this for details endpoint)
name string Company name
registrationNumber string Company registration/incorporation number
incorporationDate string Date of incorporation (YYYY-MM-DD format)
dissolutionDate string Date of dissolution if dissolved (null if active)
incorporationCountry string Two-letter country code (ISO-2)
incorporationCountryName string Human-readable country name
incorporationType string Type of incorporation (e.g., "Private Limited Company")
active boolean Whether company is currently active
address object Registered address (line1, city, postalCode, country)

Example Response

{
  "items": [
    {
      "id": "cc_12345abcde",
      "name": "Acme Corporation Ltd",
      "registrationNumber": "12345678",
      "incorporationDate": "2015-03-15",
      "dissolutionDate": null,
      "incorporationCountry": "GB",
      "incorporationCountryName": "United Kingdom",
      "incorporationType": "Private Limited Company",
      "active": true,
      "address": {
        "line1": "10 Downing Street",
        "city": "London",
        "postalCode": "SW1A 2AA",
        "country": "GB"
      }
    }
  ],
  "totalItems": 1,
  "cached": false
}

Company Details Object

Full company profile including all basic information plus officers, owners, filings, and industry classifications.

Additional Attributes (Beyond Search)

Field Type Description
officers array List of directors/officers (name, role, dateOfBirth, appointedDate)
owners array List of shareholders/owners (name, ownershipPercentage, shareClass)
filings array Company filings/documents (title, filingDate, url)
industryCodes array Industry classification codes (SIC, NAICS, etc.)
website string Company website URL
email string Company email address
phone string Company phone number
tradingNames array Alternative trading names
previousNames array Historical company names

Example Officer Object

{
  "name": "John Smith",
  "role": "Director",
  "dateOfBirth": "1975-06-15",
  "nationality": "GB",
  "appointedDate": "2015-03-15",
  "resignedDate": null,
  "address": {
    "line1": "123 High Street",
    "city": "London",
    "postalCode": "SW1A 1AA",
    "country": "GB"
  }
}

Example Owner Object

{
  "name": "Jane Doe",
  "ownershipPercentage": 75.0,
  "shareClass": "Ordinary",
  "dateOfBirth": "1980-03-22",
  "nationality": "GB"
}

Search Companies

Search for companies by legal name and jurisdiction. Returns a list of matching companies with basic information. First search charges 1 credit, cached results are free.

POST /api/v1/company-search/

Request Body

Field Type Required Description
company_name string Yes Company legal name to search for (min 2 characters)
jurisdiction string Yes Two-letter ISO country code (e.g., "US", "GB", "CA")

Response (200 OK)

{
  "items": [
    {
      "id": "cc_12345abcde",
      "name": "Acme Corporation Ltd",
      "registrationNumber": "12345678",
      "incorporationDate": "2015-03-15",
      "incorporationCountry": "GB",
      "incorporationCountryName": "United Kingdom",
      "incorporationType": "Private Limited Company",
      "active": true,
      "address": {
        "line1": "10 Downing Street",
        "city": "London",
        "postalCode": "SW1A 2AA",
        "country": "GB"
      }
    }
  ],
  "totalItems": 1,
  "cached": false
}

Error Responses

400 Bad Request - Invalid Parameters

{
  "company_name": [
    "Company name must be at least 2 characters"
  ],
  "jurisdiction": [
    "Invalid jurisdiction code: 'USA'. Must be a valid 2-letter ISO country code"
  ]
}

402 Payment Required - Insufficient Credits

{
  "error": "Insufficient credits",
  "detail": "Your account has 0 credits remaining. Company search requires 1 credit."
}

429 Too Many Requests - Rate Limit

{
  "error": "Rate limit exceeded",
  "detail": "You have exceeded the rate limit for this endpoint. Please try again later.",
  "retry_after": 45
}

500 Internal Server Error

{
  "error": "Search failed",
  "detail": "ComplyCube API error: Service temporarily unavailable"
}

Get Company Details

Retrieve detailed information about a company by its ID. Returns comprehensive data including officers, owners, filings, and industry codes. This endpoint is free - no credits charged.

GET /api/v1/company-search/{company_id}/

Path Parameters

Parameter Type Description
company_id string Company ID from search results

Response (200 OK)

{
  "id": "cc_12345abcde",
  "name": "Acme Corporation Ltd",
  "registrationNumber": "12345678",
  "incorporationDate": "2015-03-15",
  "incorporationCountry": "GB",
  "incorporationCountryName": "United Kingdom",
  "incorporationType": "Private Limited Company",
  "active": true,
  "address": {
    "line1": "10 Downing Street",
    "city": "London",
    "postalCode": "SW1A 2AA",
    "country": "GB"
  },
  "officers": [
    {
      "name": "John Smith",
      "role": "Director",
      "appointedDate": "2015-03-15",
      "nationality": "GB"
    }
  ],
  "owners": [
    {
      "name": "Jane Doe",
      "ownershipPercentage": 75.0,
      "shareClass": "Ordinary"
    }
  ],
  "filings": [
    {
      "title": "Annual Return 2025",
      "filingDate": "2025-12-31",
      "description": "Annual financial statement"
    }
  ],
  "industryCodes": [
    {
      "type": "SIC",
      "code": "62011",
      "description": "Ready-made interactive leisure and entertainment software development"
    }
  ],
  "website": "https://acmecorp.com",
  "email": "[email protected]",
  "tradingNames": ["Acme Ltd"],
  "cached": false
}

Error Responses

404 Not Found

{
  "error": "Company not found",
  "detail": "No company found with ID: cc_invalid123"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "detail": "You have exceeded the rate limit for this endpoint. Please try again later.",
  "retry_after": 30
}

Rate Limits

Company search endpoints have different rate limits based on cost and expected usage patterns.

Limits by Endpoint

Endpoint Limit Window
Search Companies 5 requests Per minute
Get Company Details 100 requests Per minute

Rate Limit Headers

All responses include rate limit information in headers:

X-RateLimit-Limit: 5
X-RateLimit-Remaining: 3
X-RateLimit-Reset: 1706699460

Exceeded Rate Limit Response (429)

{
  "error": "Rate limit exceeded",
  "detail": "You have exceeded the rate limit for this endpoint. Please try again later.",
  "retry_after": 45
}
Why Different Limits?

Search is limited to 5/min because it charges credits and calls external APIs. Details is higher (100/min) because it's free and primarily serves cached data.

↑ ↓ to navigate • Enter to select • Esc to close