CompanySearchRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/desearch-ai/json-schema/desearch-ai-company-search-request-schema.json",
  "title": "CompanySearchRequest",
  "description": "Find companies from a description and collect their public contact data.",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/desearch-ai-openapi.json#/components/schemas/CompanySearchRequest",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 1000,
      "minLength": 3,
      "title": "Query",
      "description": "The companies you are looking for, in plain language: what they do, where, how far along."
    },
    "count": {
      "type": "integer",
      "maximum": 200.0,
      "minimum": 5.0,
      "title": "Count",
      "description": "How many companies to deliver. The task reserves this many at the route price and bills only the companies it delivers (a minimum applies when it delivers any; a task that delivers none is free).",
      "default": 25
    },
    "min_score": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 100.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Min Score",
      "description": "Only deliver companies with at least this fit score (0-100)."
    },
    "exclude": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array",
          "maxItems": 1000
        },
        {
          "type": "null"
        }
      ],
      "title": "Exclude",
      "description": "Companies to leave out, as domains or URLs, for example ones you already contacted. Each is reduced to its host without `www.`. Up to 1,000."
    },
    "roles": {
      "items": {
        "type": "string",
        "enum": [
          "ceo",
          "founder",
          "cto",
          "cfo",
          "coo",
          "cmo",
          "president",
          "owner",
          "managing_director"
        ]
      },
      "type": "array",
      "minItems": 1,
      "title": "Roles",
      "description": "The leaders to look for: any of `ceo`, `founder`, `cto`, `cfo`, `coo`, `cmo`, `president`, `owner`, `managing_director`. A managing director (Geschäftsführer) counts as `ceo` when `ceo` is asked for.",
      "default": [
        "ceo",
        "founder",
        "cto",
        "cfo"
      ]
    },
    "infer_emails": {
      "type": "boolean",
      "title": "Infer Emails",
      "description": "Guess leaders' emails from the company's address pattern (for example `first.last`), learned from the addresses found on its site. Inferred emails say `source: inferred` and a `confidence`.",
      "default": true
    },
    "verify_emails": {
      "type": "boolean",
      "title": "Verify Emails",
      "description": "Check every email: syntax, mail server (MX) and, for inferred ones, a web search. Each email then has a `verification`. Turn off to finish sooner without it.",
      "default": true
    },
    "filters": {
      "anyOf": [
        {
          "$ref": "#/$defs/CompanySearchFilters"
        },
        {
          "type": "null"
        }
      ]
    },
    "metadata": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string",
            "maxLength": 200
          },
          "propertyNames": {
            "pattern": "^[a-z0-9_.-]{1,40}$"
          },
          "type": "object",
          "maxProperties": 10
        },
        {
          "type": "null"
        }
      ],
      "title": "Metadata",
      "description": "Your own labels for this task, e.g. the workspace or campaign it belongs to. At most 10 keys; keys are 1-40 characters of a-z, 0-9, '_', '.' or '-'; values are strings of at most 200 characters. Returned as `metadata` on the task and usable as a filter on `GET /desearch/companies/tasks` (`metadata.<key>=<value>`). Never used by the task itself."
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "query"
  ],
  "$defs": {
    "CompanySearchFilters": {
      "properties": {
        "countries": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array",
              "maxItems": 20
            },
            {
              "type": "null"
            }
          ],
          "title": "Countries",
          "description": "Where the companies should be: ISO 3166-1 alpha-2 codes (`DE`) or country names. Scoring treats them as a location criterion. Up to 20."
        },
        "require": {
          "anyOf": [
            {
              "items": {
                "type": "string",
                "enum": [
                  "email",
                  "phone",
                  "linkedin",
                  "leader",
                  "leader_email"
                ]
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Require",
          "description": "Only deliver companies that have all of these: `email`, `phone`, `linkedin` (the company's LinkedIn page), `leader` (one of `roles`), `leader_email` (a leader with an email). A company is published once the stage that can show them has run (`email`, `phone`, `linkedin`: the contact pages; `leader`: the leaders; `leader_email`: the email checks). One that does not have them then is not delivered and not billed."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "title": "CompanySearchFilters"
    }
  }
}