{
  "info": {
    "name": "CompanyLens API",
    "_postman_id": "companylens-api-collection",
    "description": "Complete API collection for the CompanyLens company registry intelligence platform.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "api_base_url",
      "value": "https://api.companylens.io",
      "description": "API service base URL"
    },
    {
      "key": "api_key",
      "value": "cl_live_YOUR_API_KEY",
      "description": "Your CompanyLens API key (cl_live_* prefix)"
    }
  ],
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{api_key}}",
        "type": "string"
      }
    ]
  },
  "item": [
    {
      "name": "Platform",
      "item": [
        {
          "name": "Health Check",
          "request": {
            "auth": { "type": "noauth" },
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/v1/health",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "health"]
            },
            "description": "Database connectivity check. Returns healthy/unhealthy status."
          },
          "response": []
        },
        {
          "name": "Platform Stats",
          "request": {
            "auth": { "type": "noauth" },
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/v1/stats",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "stats"]
            },
            "description": "Platform-wide statistics: entity/officer/beneficial owner counts and last ETL run time."
          },
          "response": []
        },
        {
          "name": "List Jurisdictions",
          "request": {
            "auth": { "type": "noauth" },
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/v1/jurisdictions",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "jurisdictions"]
            },
            "description": "Available jurisdictions with metadata and per-resource endpoint availability."
          },
          "response": []
        },
        {
          "name": "Get Usage",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/v1/usage",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "usage"]
            },
            "description": "Returns the authenticated user's current plan tier, rate limits, and usage for the active billing period. Does not consume quota (cost 0)."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Companies",
      "item": [
        {
          "name": "Search Companies",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/v1/companies/search?q=acme&jurisdiction=uk&limit=20",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "companies", "search"],
              "query": [
                { "key": "q", "value": "acme", "description": "Search query (min 2 characters)" },
                { "key": "jurisdiction", "value": "uk", "description": "Jurisdiction slug filter", "disabled": false },
                { "key": "status", "value": "active", "description": "Company status filter", "disabled": true },
                { "key": "incorporatedAfter", "value": "2020-01-01", "description": "YYYY-MM-DD", "disabled": true },
                { "key": "incorporatedBefore", "value": "2024-01-01", "description": "YYYY-MM-DD", "disabled": true },
                { "key": "entityType", "value": "", "description": "Entity type filter", "disabled": true },
                { "key": "hasCharges", "value": "true", "description": "Filter by whether company has charges", "disabled": true },
                { "key": "cursor", "value": "", "description": "Pagination cursor", "disabled": true },
                { "key": "limit", "value": "20", "description": "Results per page (max 100)" }
              ]
            },
            "description": "Fuzzy search for companies by name across all jurisdictions. Cache: 300s."
          },
          "response": []
        },
        {
          "name": "Autocomplete Companies",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/v1/companies/autocomplete?q=acme&limit=10",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "companies", "autocomplete"],
              "query": [
                { "key": "q", "value": "acme", "description": "Search query (min 2 characters, required)" },
                { "key": "jurisdiction", "value": "gb", "description": "Jurisdiction slug filter", "disabled": true },
                { "key": "status", "value": "active", "description": "Company status filter (default: active)", "disabled": true },
                { "key": "limit", "value": "10", "description": "Results limit (max 20)" }
              ]
            },
            "description": "Fast typeahead autocomplete — prefix match first, trigram fallback for typos. Cache: 60s."
          },
          "response": []
        },
        {
          "name": "Get Company",
          "request": {
            "method": "GET",
            "header": [
              { "key": "If-None-Match", "value": "", "description": "ETag from previous response for conditional fetch", "disabled": true }
            ],
            "url": {
              "raw": "{{api_base_url}}/api/v1/companies/gb/00000006",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "companies", "gb", "00000006"]
            },
            "description": "Full company profile including officers and beneficial owners. Supports ETag conditional requests. Cache: 3600s."
          },
          "response": []
        },
        {
          "name": "Get Company Officers",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/v1/companies/gb/00000006/officers?limit=20",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "companies", "gb", "00000006", "officers"],
              "query": [
                { "key": "sort", "value": "appointedDate", "description": "Sort field: name | appointedDate | resignedDate", "disabled": true },
                { "key": "order", "value": "desc", "description": "Sort order: asc | desc", "disabled": true },
                { "key": "cursor", "value": "", "description": "Pagination cursor", "disabled": true },
                { "key": "limit", "value": "20", "description": "Results per page (max 100)" }
              ]
            },
            "description": "Paginated list of company officers. Cache: 3600s."
          },
          "response": []
        },
        {
          "name": "Get Company Beneficial Owners",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/v1/companies/gb/00000006/beneficial-owners?limit=20",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "companies", "gb", "00000006", "beneficial-owners"],
              "query": [
                { "key": "cursor", "value": "", "description": "Pagination cursor", "disabled": true },
                { "key": "limit", "value": "20", "description": "Results per page (max 100)" }
              ]
            },
            "description": "Paginated list of beneficial owners (PSCs). Cache: 3600s."
          },
          "response": []
        },
        {
          "name": "Get Company Network",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/v1/companies/gb/00000006/network",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "companies", "gb", "00000006", "network"],
              "query": [
                { "key": "cursor", "value": "", "description": "Pagination cursor", "disabled": true },
                { "key": "limit", "value": "50", "description": "Results per page (fixed max 50)", "disabled": true }
              ]
            },
            "description": "Companies linked via shared officers or beneficial owners, with the shared person identified. Cache: 3600s."
          },
          "response": []
        },
        {
          "name": "Get Company Charges",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/v1/companies/gb/00000006/charges?limit=20",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "companies", "gb", "00000006", "charges"],
              "query": [
                { "key": "cursor", "value": "", "description": "Pagination cursor", "disabled": true },
                { "key": "limit", "value": "20", "description": "Results per page (max 100)" }
              ]
            },
            "description": "Paginated list of registered charges (mortgages) against the company. Cache: 3600s."
          },
          "response": []
        },
        {
          "name": "Companies by Address",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/v1/companies/gb/by-address?address=1%20London%20Bridge&limit=20",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "companies", "gb", "by-address"],
              "query": [
                { "key": "address", "value": "1 London Bridge", "description": "Company address (required)" },
                { "key": "cursor", "value": "", "description": "Pagination cursor", "disabled": true },
                { "key": "limit", "value": "20", "description": "Results per page (max 100)" }
              ]
            },
            "description": "Companies at the same address within a jurisdiction. Jurisdiction is a path parameter. Exact match first, falls back to trigram similarity (threshold 0.55). Cache: 300s."
          },
          "response": []
        },
        {
          "name": "Batch Lookup Companies",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"companies\": [\n    { \"jurisdiction\": \"gb\", \"number\": \"00000006\" },\n    { \"jurisdiction\": \"gb\", \"number\": \"00000009\" },\n    { \"jurisdiction\": \"ie\", \"number\": \"123456\" }\n  ]\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{api_base_url}}/api/v1/companies/batch",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "companies", "batch"]
            },
            "description": "Batch lookup up to 50 companies by jurisdiction and registration number. Each lookup consumes 1 rate limit unit."
          },
          "response": []
        }
      ]
    },
    {
      "name": "People",
      "item": [
        {
          "name": "Search People (Unified)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/v1/people/search?q=john%20smith&limit=20",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "people", "search"],
              "query": [
                { "key": "q", "value": "john smith", "description": "Search query (min 2 characters, required)" },
                { "key": "jurisdiction", "value": "gb", "description": "Jurisdiction slug filter", "disabled": true },
                { "key": "cursor", "value": "", "description": "Pagination cursor", "disabled": true },
                { "key": "limit", "value": "20", "description": "Results per page (max 100)" }
              ]
            },
            "description": "Unified fuzzy search across officers, beneficial owners, and disqualified directors. Cache: 300s."
          },
          "response": []
        },
        {
          "name": "Search Officers",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/v1/people/officers/search?q=john%20smith&limit=20",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "people", "officers", "search"],
              "query": [
                { "key": "q", "value": "john smith", "description": "Search query (min 2 characters, required)" },
                { "key": "jurisdiction", "value": "gb", "description": "Jurisdiction slug filter", "disabled": true },
                { "key": "activeOnly", "value": "true", "description": "Only return active officers", "disabled": true },
                { "key": "cursor", "value": "", "description": "Pagination cursor", "disabled": true },
                { "key": "limit", "value": "20", "description": "Results per page (max 100)" }
              ]
            },
            "description": "Fuzzy search for company directors and officers by name. Cache: 300s."
          },
          "response": []
        },
        {
          "name": "Search Beneficial Owners",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/v1/people/beneficial-owners/search?q=john%20smith&limit=20",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "people", "beneficial-owners", "search"],
              "query": [
                { "key": "q", "value": "john smith", "description": "Search query (min 2 characters, required)" },
                { "key": "jurisdiction", "value": "gb", "description": "Jurisdiction slug filter", "disabled": true },
                { "key": "cursor", "value": "", "description": "Pagination cursor", "disabled": true },
                { "key": "limit", "value": "20", "description": "Results per page (max 100)" }
              ]
            },
            "description": "Fuzzy search for beneficial owners by name. Cache: 300s."
          },
          "response": []
        },
        {
          "name": "Search Disqualified Directors",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/v1/people/disqualified-directors/search?q=john%20smith&limit=20",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "people", "disqualified-directors", "search"],
              "query": [
                { "key": "q", "value": "john smith", "description": "Search query (min 2 characters, required)" },
                { "key": "jurisdiction", "value": "gb", "description": "Jurisdiction slug filter (GB-only data — only 'uk'/'gb' returns results)", "disabled": true },
                { "key": "cursor", "value": "", "description": "Pagination cursor", "disabled": true },
                { "key": "limit", "value": "20", "description": "Results per page (max 100)" }
              ]
            },
            "description": "Fuzzy search for disqualified directors by name (GB-only data). Cache: 300s."
          },
          "response": []
        },
        {
          "name": "Get Person Profile",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/v1/people/gb/00000000-0000-0000-0000-000000000000",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "people", "gb", "00000000-0000-0000-0000-000000000000"]
            },
            "description": "Unified person profile by jurisdiction and internal UUID. Use the 'id' field returned by search endpoints. Cache: 3600s."
          },
          "response": []
        },
        {
          "name": "Get Disqualified Director",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/v1/people/disqualified-directors/gb/person123",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "people", "disqualified-directors", "gb", "person123"]
            },
            "description": "Full disqualified director profile by jurisdiction and Companies House person ID. Jurisdiction is required (gb/uk only). Cache: 3600s."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Me",
      "item": [
        {
          "name": "List API Keys",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/v1/me/keys",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "me", "keys"],
              "query": [
                { "key": "limit", "value": "20", "description": "Results per page (max 100)", "disabled": true }
              ]
            },
            "description": "List all API keys belonging to the authenticated user."
          },
          "response": []
        },
        {
          "name": "Deactivate API Key",
          "request": {
            "method": "DELETE",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/v1/me/keys/123",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "me", "keys", "123"]
            },
            "description": "Deactivate an API key by ID. Returns 204 on success, 404 if the key does not exist or belongs to another user."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Organisations",
      "item": [
        {
          "name": "Create Organisation",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"name\": \"Acme Corp\",\n  \"seatCount\": 5\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{api_base_url}}/api/orgs",
              "host": ["{{api_base_url}}"],
              "path": ["api", "orgs"]
            },
            "description": "Create a new organisation and add the caller as owner. seatCount defaults to 3 if omitted (min 3, max 500). Returns 409 if the user already belongs to an organisation."
          },
          "response": []
        },
        {
          "name": "Get My Organisation",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/orgs/me",
              "host": ["{{api_base_url}}"],
              "path": ["api", "orgs", "me"]
            },
            "description": "Get the current user's organisation with member list and pooled usage. Returns 404 if the user is not a member of any organisation."
          },
          "response": []
        },
        {
          "name": "Update Organisation",
          "request": {
            "method": "PATCH",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"name\": \"Acme Corporation\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{api_base_url}}/api/orgs/me",
              "host": ["{{api_base_url}}"],
              "path": ["api", "orgs", "me"]
            },
            "description": "Update organisation name or seat count (owner only). At least one field required. Seat count changes for organisations with an active Stripe subscription must be made through the dashboard."
          },
          "response": []
        },
        {
          "name": "Invite Member",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"colleague@example.com\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{api_base_url}}/api/orgs/me/invites",
              "host": ["{{api_base_url}}"],
              "path": ["api", "orgs", "me", "invites"]
            },
            "description": "Invite a user by email. Creates a 7-day invite token. Caller must be an owner or admin. Returns the invite token."
          },
          "response": []
        },
        {
          "name": "Accept Invite",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/orgs/invites/00000000-0000-0000-0000-000000000000",
              "host": ["{{api_base_url}}"],
              "path": ["api", "orgs", "invites", "00000000-0000-0000-0000-000000000000"]
            },
            "description": "Accept an invite token. The authenticated user joins the organisation. Returns 404 if the token is not found, 410 if expired."
          },
          "response": []
        },
        {
          "name": "Remove Member",
          "request": {
            "method": "DELETE",
            "header": [],
            "url": {
              "raw": "{{api_base_url}}/api/orgs/me/members/456",
              "host": ["{{api_base_url}}"],
              "path": ["api", "orgs", "me", "members", "456"]
            },
            "description": "Remove a member from the organisation by user ID. Caller must be an owner or admin. Owners cannot remove themselves — transfer ownership first."
          },
          "response": []
        }
      ]
    }
  ]
}