---
title: Search for an entity
slug: andrei/search-for-an-entity
createdAt: 2026-10-05T10:36:01.732Z
---

{
  "id": "zSyfvWg5nU7GepxB0D3YO",
  "type": "api-oas-v2",
  "data": {
    "method": "POST",
    "url": "https://api.detected.app/api/v2/public/search",
    "servers": [
      {
        "url": "https://api.detected.app/api/v2/public/search",
        "description": "Production"
      }
    ],
    "name": "Search for an entity",
    "description": "<p>Searches for a company or other entity using criteria such as its name, company number and VAT number. We query several data providers and return the most relevant results. Each result is scored against your search criteria using fuzzy matching. Some providers also do fuzzy matching, and others do not. Each result shows which provider supplied it.</p>\n<h3>Creating a profile from a search result</h3>\n<p>You can create a profile directly from a search result. Send the <code>lookup_id</code> from the response, and the <code>response_id</code> of the result you want, to <code>POST /profiles</code>. See the examples on that endpoint.</p>",
    "contentType": "application/json",
    "request": {
      "pathParameters": [],
      "headerParameters": [
        {
          "name": "accept",
          "type": "string",
          "kind": "optional",
          "description": "Generated from available response content types",
          "enum": [
            "application/json"
          ],
          "default": "application/json"
        }
      ],
      "queryParameters": [],
      "bodyDataParameters": [
        {
          "kind": "optional",
          "name": "body",
          "type": "object",
          "description": "",
          "customType": "SearchRequest",
          "schema": [
            {
              "name": "type",
              "kind": "required",
              "type": "string<company | sole_trader | partnership | charity | government_entity | incorporated_syndicate | company_syndicate | syndicate | association | trust | fund | club | individual | joint_individual>",
              "description": "Entity type to search for.",
              "enum": [
                "company",
                "sole_trader",
                "partnership",
                "charity",
                "government_entity",
                "incorporated_syndicate",
                "company_syndicate",
                "syndicate",
                "association",
                "trust",
                "fund",
                "club",
                "individual",
                "joint_individual"
              ]
            },
            {
              "name": "name",
              "kind": "required",
              "type": "string",
              "description": "Name of the company to search for."
            },
            {
              "name": "vat_number",
              "kind": "optional",
              "type": "string",
              "description": "VAT number."
            },
            {
              "name": "company_reference",
              "kind": "optional",
              "type": "string",
              "description": "<p>Deprecated. Use <code>company_number</code> instead.</p>"
            },
            {
              "name": "company_number",
              "kind": "optional",
              "type": "string",
              "description": "Official company registration number or identifier used for searching."
            },
            {
              "name": "address",
              "kind": "required",
              "type": "object",
              "description": "Address to search in.",
              "example": "",
              "schema": [
                {
                  "name": "line_1",
                  "kind": "optional",
                  "type": "string",
                  "description": "First line of the address."
                },
                {
                  "name": "line_2",
                  "kind": "optional",
                  "type": "string",
                  "description": "Second line of the address."
                },
                {
                  "name": "country_code",
                  "kind": "required",
                  "type": "string",
                  "description": "<p>Country to search in, ISO 3166-1 alpha-2 country code.</p>"
                },
                {
                  "name": "town",
                  "kind": "optional",
                  "type": "string",
                  "description": "Town."
                },
                {
                  "name": "city",
                  "kind": "required",
                  "type": "string",
                  "description": "City."
                },
                {
                  "name": "post_code",
                  "kind": "optional",
                  "type": "string",
                  "description": "Postcode."
                },
                {
                  "name": "province",
                  "kind": "optional",
                  "type": "string",
                  "description": "Province."
                },
                {
                  "name": "state",
                  "kind": "optional",
                  "type": "string",
                  "description": "State or region."
                }
              ]
            }
          ],
          "modelRef": "#/components/schemas/SearchRequest",
          "isExpanded": true
        }
      ],
      "formDataParameters": [],
      "oAuthParameters": [
        {
          "id": "AccessToken",
          "name": "AccessToken",
          "kind": "optional",
          "type": "http",
          "description": "<p>The API uses OAuth 2.0. Request an access token from <code>POST /oauth/token</code> with the client ID and client secret of your integration client, and your account slug. Send the access token in the <code>Authorization</code> header of every request, in the format <code>Authorization: Bearer &#x3C;access_token></code>. The access token carries the scopes set on your integration client in the dashboard. Access tokens expire. When one expires, request a new one.</p>",
          "scheme": "bearer"
        }
      ],
      "cookieParameters": []
    },
    "responses": [
      {
        "statusCode": "200",
        "description": "OK",
        "jsonExample": "",
        "isExpanded": true,
        "headers": [
          {
            "kind": "optional",
            "name": "X-RateLimit-Limit",
            "description": ""
          },
          {
            "kind": "optional",
            "name": "X-RateLimit-Remaining",
            "description": ""
          },
          {
            "kind": "optional",
            "name": "x-ratelimit-reset",
            "description": ""
          },
          {
            "kind": "optional",
            "name": "retry-after",
            "description": ""
          }
        ],
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "",
            "customType": "SearchResponse",
            "schema": [
              {
                "name": "data",
                "kind": "optional",
                "type": "array",
                "description": "List of search results.",
                "example": "",
                "itemType": "object",
                "customType": "object[]",
                "schema": [
                  {
                    "name": "type",
                    "kind": "optional",
                    "type": "string<company | sole_trader | partnership | charity | government_entity | incorporated_syndicate | company_syndicate | syndicate | association | trust | fund | club | individual | joint_individual>",
                    "description": "Entity type of the result.",
                    "enum": [
                      "company",
                      "sole_trader",
                      "partnership",
                      "charity",
                      "government_entity",
                      "incorporated_syndicate",
                      "company_syndicate",
                      "syndicate",
                      "association",
                      "trust",
                      "fund",
                      "club",
                      "individual",
                      "joint_individual"
                    ]
                  },
                  {
                    "name": "name",
                    "kind": "optional",
                    "type": "string",
                    "description": "Company name."
                  },
                  {
                    "name": "company_reference",
                    "kind": "optional",
                    "type": "string",
                    "description": "<p>Company reference number, as supplied by the provider.</p>"
                  },
                  {
                    "name": "provider",
                    "kind": "optional",
                    "type": "string",
                    "description": "Data provider that supplied the result."
                  },
                  {
                    "name": "provider_reference",
                    "kind": "optional",
                    "type": "string",
                    "description": "Reference of the company at the provider."
                  },
                  {
                    "name": "jurisdiction_code",
                    "kind": "optional",
                    "type": "string",
                    "description": "<p>Jurisdiction code of the company, for example <code>gb</code>.</p>"
                  },
                  {
                    "name": "company_type",
                    "kind": "optional",
                    "type": "string",
                    "description": "<p>Type of company, for example <code>PRIVATE LIMITED COMPANY</code>.</p>"
                  },
                  {
                    "name": "current_status",
                    "kind": "optional",
                    "type": "string",
                    "description": "<p>Current status of the company, for example <code>Dissolved</code>.</p>"
                  },
                  {
                    "name": "address",
                    "kind": "optional",
                    "type": "string",
                    "description": "Address of the company."
                  },
                  {
                    "name": "vat_number",
                    "kind": "optional",
                    "type": "string",
                    "description": "<p>VAT number of the company, if known.</p>"
                  },
                  {
                    "name": "province_code",
                    "kind": "optional",
                    "type": "string",
                    "description": "Province or region code of the company's address."
                  },
                  {
                    "name": "post_code",
                    "kind": "optional",
                    "type": "string",
                    "description": "Postcode of the company address."
                  },
                  {
                    "name": "city",
                    "kind": "optional",
                    "type": "string",
                    "description": "City of the company address."
                  },
                  {
                    "name": "confidence",
                    "kind": "optional",
                    "type": "integer",
                    "description": "Confidence score of the match."
                  },
                  {
                    "name": "response_id",
                    "kind": "optional",
                    "type": "integer",
                    "description": "<p>ID of this result. Send it, with <code>lookup_id</code>, to <code>POST /profiles</code> to create a profile from the result.</p>"
                  }
                ]
              },
              {
                "name": "status",
                "kind": "optional",
                "type": "string<EMPTY | PARTIAL | MATCH>",
                "description": "<p>Outcome of the search: <code>EMPTY</code> if there are no results, <code>PARTIAL</code> if the results only partly match, or <code>MATCH</code> if there is a match.</p>",
                "enum": [
                  "EMPTY",
                  "PARTIAL",
                  "MATCH"
                ]
              },
              {
                "name": "lookup_id",
                "kind": "optional",
                "type": "integer",
                "description": "<p>ID of this search. Send it, with the <code>response_id</code> of a result, to <code>POST /profiles</code> to create a profile from the result.</p>"
              }
            ],
            "modelRef": "#/components/schemas/SearchResponse",
            "isExpanded": true
          }
        ]
      },
      {
        "statusCode": "401",
        "description": "<p>Unauthorized. The access token is missing, invalid or has expired.</p>",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "",
            "schema": [
              {
                "name": "message",
                "kind": "optional",
                "type": "string",
                "description": "<p>A human-readable description of the error.</p>"
              }
            ],
            "isExpanded": true
          }
        ]
      },
      {
        "statusCode": "404",
        "description": "<p>Not Found. The requested resource does not exist, or is not available to your account.</p>",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "",
            "schema": [
              {
                "name": "message",
                "kind": "optional",
                "type": "string",
                "description": "<p>A human-readable description of the error.</p>"
              }
            ],
            "isExpanded": true
          }
        ]
      },
      {
        "statusCode": "422",
        "description": "Unprocessable Content. The request was understood but failed validation. The response lists the fields that failed and why.",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "",
            "schema": [
              {
                "name": "message",
                "kind": "optional",
                "type": "string",
                "description": "<p>A human-readable description of the error.</p>"
              },
              {
                "name": "example_field",
                "kind": "optional",
                "type": "array",
                "description": "<p>Validation errors for one field of the request body. The property name is the name of the field that failed validation (<code>example_field</code> is a placeholder).</p>",
                "example": "",
                "itemType": "string",
                "customType": "string[]",
                "itemExample": "",
                "itemDefault": ""
              }
            ],
            "isExpanded": true
          }
        ]
      },
      {
        "statusCode": "429",
        "description": "<p>Too Many Requests. You have exceeded the rate limit. Wait for the number of seconds given in the <code>Retry-After</code> header before trying again.</p>",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "",
            "schema": [
              {
                "name": "message",
                "kind": "optional",
                "type": "string",
                "description": "<p>A human-readable description of the error.</p>"
              }
            ],
            "isExpanded": true
          }
        ]
      }
    ],
    "hasXCodeSamples": false,
    "examples": {
      "languages": [
        {
          "id": "example-0-curl",
          "language": "curl",
          "label": "cURL",
          "code": "curl --request POST \\\n     --url https://api.detected.app/api/v2/public/search \\\n     --header 'accept: application/json' \\\n     --header 'content-type: application/json' \\\n     --data '{\n     \"type\": \"\",\n     \"name\": \"\",\n     \"address\": {\n     \"country_code\": \"\",\n     \"city\": \"\"\n     }\n     }'"
        },
        {
          "id": "example-1-javascript",
          "language": "javascript",
          "label": "javascript",
          "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n   \"type\": \"\",\n   \"name\": \"\",\n   \"address\": {\n      \"country_code\": \"\",\n      \"city\": \"\"\n   }\n});\n\nvar requestOptions = {\n   method: 'POST',\n   headers: myHeaders,\n   body: raw,\n   redirect: 'follow'\n};\n\nfetch(\"https://api.detected.app/api/v2/public/search\", requestOptions)\n   .then(response => response.text())\n   .then(result => console.log(result))\n   .catch(error => console.log('error', error));"
        },
        {
          "id": "example-2-ruby",
          "language": "ruby",
          "label": "Ruby",
          "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.detected.app/api/v2/public/search\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n   \"type\": \"\",\n   \"name\": \"\",\n   \"address\": {\n      \"country_code\": \"\",\n      \"city\": \"\"\n   }\n})\n\nresponse = https.request(request)\nputs response.read_body\n"
        },
        {
          "id": "example-3-python",
          "language": "python",
          "label": "Python",
          "code": "import requests\nimport json\n\nurl = \"https://api.detected.app/api/v2/public/search\"\n\npayload = json.dumps({\n   \"type\": \"\",\n   \"name\": \"\",\n   \"address\": {\n      \"country_code\": \"\",\n      \"city\": \"\"\n   }\n})\nheaders = {\n   'accept': 'application/json',\n   'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n"
        }
      ],
      "selectedLanguageId": "example-0-curl"
    },
    "results": {
      "languages": [
        {
          "id": "response-0-200",
          "language": "200",
          "code": "// OK\n{\n  \"data\": [\n    {\n      \"type\": \"\",\n      \"name\": \"\",\n      \"company_reference\": \"\",\n      \"provider\": \"\",\n      \"provider_reference\": \"\",\n      \"jurisdiction_code\": \"\",\n      \"company_type\": \"\",\n      \"current_status\": \"\",\n      \"address\": \"\",\n      \"vat_number\": \"\",\n      \"province_code\": \"\",\n      \"post_code\": \"\",\n      \"city\": \"\",\n      \"confidence\": 0,\n      \"response_id\": 0\n    }\n  ],\n  \"status\": \"\",\n  \"lookup_id\": 0\n}"
        },
        {
          "id": "response-1-401",
          "language": "401",
          "code": "// Unauthorized. The access token is missing, invalid or has expired.\n{\n  \"message\": \"\"\n}"
        },
        {
          "id": "response-2-404",
          "language": "404",
          "code": "// Not Found. The requested resource does not exist, or is not available to your account.\n{\n  \"message\": \"\"\n}"
        },
        {
          "id": "response-3-422",
          "language": "422",
          "code": "// Unprocessable Content. The request was understood but failed validation. The response lists the fields that failed and why.\n{\n  \"message\": \"\",\n  \"example_field\": [\n    \"\"\n  ]\n}"
        },
        {
          "id": "response-4-429",
          "language": "429",
          "code": "// Too Many Requests. You have exceeded the rate limit. Wait for the number of seconds given in the Retry-After header before trying again.\n{\n  \"message\": \"\"\n}"
        }
      ],
      "selectedLanguageId": "response-0-200"
    }
  },
  "children": [
    {
      "text": ""
    }
  ]
}