---
updatedAt: 2026-08-11T21:30:36.000Z
agentTools:
  projectIndex: https://docs.dotfile.com/llms.txt
---

# Search companies

Search companies by name or registration number.

---

#### See also  
Learn more about [Company data](./company-data-guide)  


# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "paths": {
    "/v1/company-data/search": {
      "get": {
        "operationId": "company-data-search",
        "summary": "Search companies",
        "description": "Search companies by name or registration number.\n\n---\n\n#### See also  \nLearn more about [Company data](./company-data-guide)  \n",
        "parameters": [
          {
            "name": "country",
            "required": true,
            "in": "query",
            "description": "Search companies in a `country`, always required  \n[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (eg `FR`)",
            "schema": {
              "minLength": 2,
              "maxLength": 2,
              "format": "alpha-2",
              "type": "string"
            }
          },
          {
            "name": "name",
            "required": false,
            "in": "query",
            "description": "Search companies by `name`.  \nIn addition to `country`, either `name` or `registration_number` is required.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "registration_number",
            "required": false,
            "in": "query",
            "description": "Search companies by `registration_number`.  \nIn addition to `country`, either `name` or `registration_number` is required.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns list of companies which matching\n\n**ℹ️ Click to see full payload**",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanySearchList"
                }
              }
            }
          },
          "400": {
            "description": "The request is either malformed or contain invalid parameters.\n\n\n  "
          }
        },
        "tags": [
          "Company data"
        ]
      }
    }
  },
  "info": {
    "title": "⚙️ API specifications",
    "description": "Dotfile public API documentation\n\n## Rate limiting\n\nRequests are counted per workspace: every API key of a workspace shares the same quota, across all of Dotfile's servers. Two independent quotas apply per one-minute window:\n\n- **Read** requests (`GET`, `HEAD`): 2,500 requests per minute by default.\n- **Write** requests (every other method): 1,500 requests per minute by default.\n\nEvery response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (Unix timestamp in seconds) and `X-RateLimit-Scope`. Once a quota is exhausted, the API answers `429 Too Many Requests` with a `Retry-After` header giving the number of seconds to wait. Every request counts, including those rejected with a `4xx` status.\n\nContact us if your integration needs a higher quota for your workspace.",
    "version": "v1",
    "contact": {}
  },
  "servers": [
    {
      "url": "https://api.dotfile.com",
      "description": "Production environment"
    }
  ],
  "components": {
    "securitySchemes": {
      "DotfileAPIKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-DOTFILE-API-KEY",
        "description": "Configure your api key in the Workspace settings"
      }
    },
    "schemas": {
      "Address": {
        "type": "object",
        "properties": {
          "street_address": {
            "type": "string",
            "nullable": true
          },
          "street_address_2": {
            "type": "string",
            "nullable": true
          },
          "postal_code": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "state": {
            "type": "string",
            "nullable": true
          },
          "region": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "format": "alpha-2",
            "minLength": 2,
            "maxLength": 2,
            "nullable": true,
            "description": "[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (eg `FR`)"
          }
        },
        "required": [
          "street_address",
          "street_address_2",
          "postal_code",
          "city",
          "state",
          "region",
          "country"
        ]
      },
      "CompanySearch": {
        "type": "object",
        "properties": {
          "country": {
            "type": "string",
            "format": "alpha-2",
            "minLength": 2,
            "maxLength": 2,
            "description": "[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (eg `FR`)"
          },
          "name": {
            "type": "string"
          },
          "search_ref": {
            "type": "string",
            "description": "Opaque string, use it to fetch the information of this company via [Fetch company data](./company-data-fetch)"
          },
          "registration_number": {
            "type": "string",
            "description": "The company's national registration number, in the form its home registry uses (a SIREN in France, a Companies House number in the UK, an EIK in Bulgaria).  \nUse `search_ref` to fetch a specific result: a registration number is not guaranteed to address exactly one company in every country."
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "disclosable": {
            "type": "boolean",
            "description": "When `false`, indicate that the company information is not fully publicly available. Company data fetch will be partial"
          },
          "status": {
            "type": "string",
            "description": "Company status (live, closed, not_reported)",
            "enum": [
              "live",
              "closed",
              "not_reported"
            ]
          }
        },
        "required": [
          "country",
          "name",
          "search_ref",
          "registration_number",
          "address",
          "disclosable",
          "status"
        ]
      },
      "CompanySearchList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CompanySearch"
            }
          }
        },
        "required": [
          "data"
        ]
      }
    }
  },
  "security": [
    {
      "DotfileAPIKey": []
    }
  ],
  "x-uploaded-at": "2026-10-29T16:29:52.073Z",
  "x-commit-sha": "b389d115e1cb6a813feec644c385eb337a90f572"
}
```