--- title: "Create Company Enrichment Job" method: POST path: "/v1/companies/enrichment-jobs" tags: ["Companies", "Enrichment", "v1"] --- # Create Company Enrichment Job `POST /v1/companies/enrichment-jobs` ## Request - Base URL: `https://api.leadfeeder.com` - URL: `https://api.leadfeeder.com/v1/companies/enrichment-jobs` - Auth: one of: - API key in header `X-Api-Key` - OAuth 2 - Authorization code: `https://api.leadfeeder.com/v1/oauth/authorize` - Token URL: `https://api.leadfeeder.com/v1/oauth/token` scopes: `companies:read` Trigger an asynchronous job to enrich companies with AI-generated custom field values. The custom field must exist and be an AI field type (`ai_score`, `ai_text`, `ai_number`, `ai_boolean`) or a `contact_collection` field. Create custom fields via the Custom Fields API first. The job runs in the background; poll the status endpoint to check progress. A maximum of 50,000 companies are enriched per job, whether targeted via `company_ids`, `list_id`, or `advanced_search`; companies beyond this limit are not processed. Split larger selections across multiple jobs. Use `advanced_search` to enrich the companies matching a search query without listing their ids yourself. You control the selection with `sort` (which matches to prefer), `page.size` (how many to enrich), and `excluded_company_ids` (matches to skip). Add a `list_id` alongside `advanced_search` to also save the matched companies to that list before they are enriched. Enrichment settings (prompt, external data usage, contact collection options) come from the custom field's saved configuration. The request may override any of them for a single run; the field's configuration is never modified. Preview: send `enrichment_strategy: "preview"` with a `prompt` and an `output_type` (no `custom_field_id` needed) to dry-run the prompt against a sample of up to 100 of the targeted companies. Nothing is written: no custom field values, no list changes. The per-company results are returned on the job resource once it completes. To preview a custom field instead, name it as `custom_field_id`: the field supplies the answer shape, so no `output_type` is needed. Previewing a `contact_collection` field returns a `contacts` list per company instead of a score. To preview contacts without a field, send `output_type: contact_collection` with the prompt; the contact settings come from the `contact_collection` object. Credit Note: Credits are consumed as companies are enriched. :::info Requires the `companies:read` OAuth2 scope. ::: ## Query parameters - `account_id` string, required ## Request body - object - `data` object, required - `attributes` union, required: Provide a target plus a `custom_field_id` identifying the custom field to enrich. The target is `company_ids`, `list_id`, or `advanced_search`. `company_ids` is mutually exclusive with the others; `list_id` and `advanced_search` may be supplied together, in which case the search results are added to the list and then enriched. All enrichment settings default to the custom field's saved configuration; the optional attributes below override them for this run only — the field's configuration is never modified. - union - object - `enrichment_strategy` 'preview', required: Which records to enrich - `advanced_search` object: A set of companies selected by an advanced search query, instead of an explicit `company_ids` list. The companies matching `filters` are taken in `sort` order, limited to `page.size`, with any `excluded_company_ids` removed. - `excluded_company_ids` string[]: Company IDs to remove from the matched set (for example, rows the user deselected). Removed after the `page.size` limit is applied, so the final selection may be smaller than `page.size`. - `filters` object, required: Recursive filter tree applied to the company population. The root is always a `group` whose `items` are either individual filters or further `group` nodes (combined with `and`/`or`). The tree holds at most 50 filters and groups, the root included, and at most 5 levels of groups. - … - `page` object: Bounds how many of the matching companies are selected. - … - `sort` object: Ordering applied to the matching companies. Omit to use the default ordering. - … - `category` string: Overrides the custom field's configured prompt category for this run. - `company_ids` string[], required: Specific company IDs to enrich. Mutually exclusive with `list_id` and `advanced_search`. - `contact_collection` object: Contact settings. On a run that names a `contact_collection` custom field they override the field's configuration for this run only. On a prompt-only preview with `output_type: contact_collection` there is no field, so they are the preview's settings. The object is always optional: a run that names a field falls back to the field's configuration, and a prompt-only preview falls back to the documented default for each setting. - `contacts_to_enrich` integer: Overrides how many of the collected contacts get their details revealed on this run. Defaults to `num_contacts_max_per_company`. - `enrich_emails` boolean: Whether email addresses are revealed for the enriched contacts. Must be present here or in the custom field's configuration, except on a prompt-only preview, which reveals nothing. - `enrich_phones` boolean: Whether phone numbers are revealed for the enriched contacts. Must be present here or in the custom field's configuration, except on a prompt-only preview, which reveals nothing. - `filter_groups` object: Restricts which contacts are collected within the targeted companies (by location, seniority, department and/or job-title keywords). When omitted, the custom field's saved contact filters apply; a prompt-only preview has no field, so no contact filter applies. - … - `find_more_contacts_details` boolean: Overrides whether details are revealed for the collected contacts on this run. - `num_contacts_max_per_company` integer: Overrides the maximum number of contacts collected per company for this run. Defaults to 10 when omitted, which is also the hard ceiling: a larger value is accepted but no run returns more than 10 contacts per company. - `custom_field_id` string: The API name of the custom field to enrich. Must be an AI field type (ai_score, ai_text, ai_number, ai_boolean) or a contact_collection field. Not required for `preview` runs, which dry-run a `prompt` instead of enriching a field; a preview that names one takes its answer shape from the field. - `limit` integer: Enrich only the first `limit` companies of the target. For `list_id` and `company_ids` they are taken in the list's default order (most complete records first). With `advanced_search`, the smaller of `limit` and the selection's `page.size` applies, in the selection's own `sort` order. Omit to enrich the whole target. A `preview` is still capped at 100 companies. - `list_id` string: The list to enrich, identified by its Lists API id (e.g. `company_12345`). Mutually exclusive with `company_ids`. When supplied together with `advanced_search`, the search results are added to this list and then enriched (instead of enriching the list's current members). - `locale` string: Locale for AI-generated output. Defaults to `en-US`. - `output_type` 'ai_score' | 'ai_text' | 'ai_number' | 'ai_boolean' | 'contact_collection', required: The answer shape the AI produces. It is normally derived from the custom field, so it is only relevant (and required) for `preview` runs that name no `custom_field_id`. A preview that names a field takes its answer shape from the field; if it also sends an `output_type`, that value must equal the field's type, or the request is rejected with a 422 `invalid_parameter` error. This applies in both directions: a scalar `output_type` on a `contact_collection` field and `contact_collection` on a scalar AI field are both rejected. `ai_score`, `ai_text`, `ai_number` and `ai_boolean` run a scalar preview that returns `score` and `reason` per company. `contact_collection` runs a contacts preview that returns a `contacts` list per company; its settings come from the `contact_collection` object. - `prompt` string, required: Overrides the custom field's configured prompt for this run. For `contact_collection` fields the prompt is typically supplied here on each run, since the field stores no prompt. Required for every `preview` run, whether it names a custom field or not. - `use_external_data` boolean: Overrides the custom field's configured setting for whether the AI may use external data sources for this run. - object - `enrichment_strategy` 'preview', required: Which records to enrich - `advanced_search` object: A set of companies selected by an advanced search query, instead of an explicit `company_ids` list. The companies matching `filters` are taken in `sort` order, limited to `page.size`, with any `excluded_company_ids` removed. - `excluded_company_ids` string[]: Company IDs to remove from the matched set (for example, rows the user deselected). Removed after the `page.size` limit is applied, so the final selection may be smaller than `page.size`. - `filters` object, required: Recursive filter tree applied to the company population. The root is always a `group` whose `items` are either individual filters or further `group` nodes (combined with `and`/`or`). The tree holds at most 50 filters and groups, the root included, and at most 5 levels of groups. - … - `page` object: Bounds how many of the matching companies are selected. - … - `sort` object: Ordering applied to the matching companies. Omit to use the default ordering. - … - `category` string: Overrides the custom field's configured prompt category for this run. - `company_ids` string[], required: Specific company IDs to enrich. Mutually exclusive with `list_id` and `advanced_search`. - `contact_collection` object: Contact settings. On a run that names a `contact_collection` custom field they override the field's configuration for this run only. On a prompt-only preview with `output_type: contact_collection` there is no field, so they are the preview's settings. The object is always optional: a run that names a field falls back to the field's configuration, and a prompt-only preview falls back to the documented default for each setting. - `contacts_to_enrich` integer: Overrides how many of the collected contacts get their details revealed on this run. Defaults to `num_contacts_max_per_company`. - `enrich_emails` boolean: Whether email addresses are revealed for the enriched contacts. Must be present here or in the custom field's configuration, except on a prompt-only preview, which reveals nothing. - `enrich_phones` boolean: Whether phone numbers are revealed for the enriched contacts. Must be present here or in the custom field's configuration, except on a prompt-only preview, which reveals nothing. - `filter_groups` object: Restricts which contacts are collected within the targeted companies (by location, seniority, department and/or job-title keywords). When omitted, the custom field's saved contact filters apply; a prompt-only preview has no field, so no contact filter applies. - … - `find_more_contacts_details` boolean: Overrides whether details are revealed for the collected contacts on this run. - `num_contacts_max_per_company` integer: Overrides the maximum number of contacts collected per company for this run. Defaults to 10 when omitted, which is also the hard ceiling: a larger value is accepted but no run returns more than 10 contacts per company. - `custom_field_id` string, required: The API name of the custom field to enrich. Must be an AI field type (ai_score, ai_text, ai_number, ai_boolean) or a contact_collection field. Not required for `preview` runs, which dry-run a `prompt` instead of enriching a field; a preview that names one takes its answer shape from the field. - `limit` integer: Enrich only the first `limit` companies of the target. For `list_id` and `company_ids` they are taken in the list's default order (most complete records first). With `advanced_search`, the smaller of `limit` and the selection's `page.size` applies, in the selection's own `sort` order. Omit to enrich the whole target. A `preview` is still capped at 100 companies. - `list_id` string: The list to enrich, identified by its Lists API id (e.g. `company_12345`). Mutually exclusive with `company_ids`. When supplied together with `advanced_search`, the search results are added to this list and then enriched (instead of enriching the list's current members). - `locale` string: Locale for AI-generated output. Defaults to `en-US`. - `output_type` 'ai_score' | 'ai_text' | 'ai_number' | 'ai_boolean' | 'contact_collection': The answer shape the AI produces. It is normally derived from the custom field, so it is only relevant (and required) for `preview` runs that name no `custom_field_id`. A preview that names a field takes its answer shape from the field; if it also sends an `output_type`, that value must equal the field's type, or the request is rejected with a 422 `invalid_parameter` error. This applies in both directions: a scalar `output_type` on a `contact_collection` field and `contact_collection` on a scalar AI field are both rejected. `ai_score`, `ai_text`, `ai_number` and `ai_boolean` run a scalar preview that returns `score` and `reason` per company. `contact_collection` runs a contacts preview that returns a `contacts` list per company; its settings come from the `contact_collection` object. - `prompt` string, required: Overrides the custom field's configured prompt for this run. For `contact_collection` fields the prompt is typically supplied here on each run, since the field stores no prompt. Required for every `preview` run, whether it names a custom field or not. - `use_external_data` boolean: Overrides the custom field's configured setting for whether the AI may use external data sources for this run. - union - object - `enrichment_strategy` 'preview', required: Which records to enrich - `advanced_search` object: A set of companies selected by an advanced search query, instead of an explicit `company_ids` list. The companies matching `filters` are taken in `sort` order, limited to `page.size`, with any `excluded_company_ids` removed. - `excluded_company_ids` string[]: Company IDs to remove from the matched set (for example, rows the user deselected). Removed after the `page.size` limit is applied, so the final selection may be smaller than `page.size`. - `filters` object, required: Recursive filter tree applied to the company population. The root is always a `group` whose `items` are either individual filters or further `group` nodes (combined with `and`/`or`). The tree holds at most 50 filters and groups, the root included, and at most 5 levels of groups. - … - `page` object: Bounds how many of the matching companies are selected. - … - `sort` object: Ordering applied to the matching companies. Omit to use the default ordering. - … - `category` string: Overrides the custom field's configured prompt category for this run. - `company_ids` string[]: Specific company IDs to enrich. Mutually exclusive with `list_id` and `advanced_search`. - `contact_collection` object: Contact settings. On a run that names a `contact_collection` custom field they override the field's configuration for this run only. On a prompt-only preview with `output_type: contact_collection` there is no field, so they are the preview's settings. The object is always optional: a run that names a field falls back to the field's configuration, and a prompt-only preview falls back to the documented default for each setting. - `contacts_to_enrich` integer: Overrides how many of the collected contacts get their details revealed on this run. Defaults to `num_contacts_max_per_company`. - `enrich_emails` boolean: Whether email addresses are revealed for the enriched contacts. Must be present here or in the custom field's configuration, except on a prompt-only preview, which reveals nothing. - `enrich_phones` boolean: Whether phone numbers are revealed for the enriched contacts. Must be present here or in the custom field's configuration, except on a prompt-only preview, which reveals nothing. - `filter_groups` object: Restricts which contacts are collected within the targeted companies (by location, seniority, department and/or job-title keywords). When omitted, the custom field's saved contact filters apply; a prompt-only preview has no field, so no contact filter applies. - … - `find_more_contacts_details` boolean: Overrides whether details are revealed for the collected contacts on this run. - `num_contacts_max_per_company` integer: Overrides the maximum number of contacts collected per company for this run. Defaults to 10 when omitted, which is also the hard ceiling: a larger value is accepted but no run returns more than 10 contacts per company. - `custom_field_id` string: The API name of the custom field to enrich. Must be an AI field type (ai_score, ai_text, ai_number, ai_boolean) or a contact_collection field. Not required for `preview` runs, which dry-run a `prompt` instead of enriching a field; a preview that names one takes its answer shape from the field. - `limit` integer: Enrich only the first `limit` companies of the target. For `list_id` and `company_ids` they are taken in the list's default order (most complete records first). With `advanced_search`, the smaller of `limit` and the selection's `page.size` applies, in the selection's own `sort` order. Omit to enrich the whole target. A `preview` is still capped at 100 companies. - `list_id` string, required: The list to enrich, identified by its Lists API id (e.g. `company_12345`). Mutually exclusive with `company_ids`. When supplied together with `advanced_search`, the search results are added to this list and then enriched (instead of enriching the list's current members). - `locale` string: Locale for AI-generated output. Defaults to `en-US`. - `output_type` 'ai_score' | 'ai_text' | 'ai_number' | 'ai_boolean' | 'contact_collection', required: The answer shape the AI produces. It is normally derived from the custom field, so it is only relevant (and required) for `preview` runs that name no `custom_field_id`. A preview that names a field takes its answer shape from the field; if it also sends an `output_type`, that value must equal the field's type, or the request is rejected with a 422 `invalid_parameter` error. This applies in both directions: a scalar `output_type` on a `contact_collection` field and `contact_collection` on a scalar AI field are both rejected. `ai_score`, `ai_text`, `ai_number` and `ai_boolean` run a scalar preview that returns `score` and `reason` per company. `contact_collection` runs a contacts preview that returns a `contacts` list per company; its settings come from the `contact_collection` object. - `prompt` string, required: Overrides the custom field's configured prompt for this run. For `contact_collection` fields the prompt is typically supplied here on each run, since the field stores no prompt. Required for every `preview` run, whether it names a custom field or not. - `use_external_data` boolean: Overrides the custom field's configured setting for whether the AI may use external data sources for this run. - object - `enrichment_strategy` 'preview', required: Which records to enrich - `advanced_search` object, required: A set of companies selected by an advanced search query, instead of an explicit `company_ids` list. The companies matching `filters` are taken in `sort` order, limited to `page.size`, with any `excluded_company_ids` removed. - `excluded_company_ids` string[]: Company IDs to remove from the matched set (for example, rows the user deselected). Removed after the `page.size` limit is applied, so the final selection may be smaller than `page.size`. - `filters` object, required: Recursive filter tree applied to the company population. The root is always a `group` whose `items` are either individual filters or further `group` nodes (combined with `and`/`or`). The tree holds at most 50 filters and groups, the root included, and at most 5 levels of groups. - … - `page` object: Bounds how many of the matching companies are selected. - … - `sort` object: Ordering applied to the matching companies. Omit to use the default ordering. - … - `category` string: Overrides the custom field's configured prompt category for this run. - `company_ids` string[]: Specific company IDs to enrich. Mutually exclusive with `list_id` and `advanced_search`. - `contact_collection` object: Contact settings. On a run that names a `contact_collection` custom field they override the field's configuration for this run only. On a prompt-only preview with `output_type: contact_collection` there is no field, so they are the preview's settings. The object is always optional: a run that names a field falls back to the field's configuration, and a prompt-only preview falls back to the documented default for each setting. - `contacts_to_enrich` integer: Overrides how many of the collected contacts get their details revealed on this run. Defaults to `num_contacts_max_per_company`. - `enrich_emails` boolean: Whether email addresses are revealed for the enriched contacts. Must be present here or in the custom field's configuration, except on a prompt-only preview, which reveals nothing. - `enrich_phones` boolean: Whether phone numbers are revealed for the enriched contacts. Must be present here or in the custom field's configuration, except on a prompt-only preview, which reveals nothing. - `filter_groups` object: Restricts which contacts are collected within the targeted companies (by location, seniority, department and/or job-title keywords). When omitted, the custom field's saved contact filters apply; a prompt-only preview has no field, so no contact filter applies. - … - `find_more_contacts_details` boolean: Overrides whether details are revealed for the collected contacts on this run. - `num_contacts_max_per_company` integer: Overrides the maximum number of contacts collected per company for this run. Defaults to 10 when omitted, which is also the hard ceiling: a larger value is accepted but no run returns more than 10 contacts per company. - `custom_field_id` string: The API name of the custom field to enrich. Must be an AI field type (ai_score, ai_text, ai_number, ai_boolean) or a contact_collection field. Not required for `preview` runs, which dry-run a `prompt` instead of enriching a field; a preview that names one takes its answer shape from the field. - `limit` integer: Enrich only the first `limit` companies of the target. For `list_id` and `company_ids` they are taken in the list's default order (most complete records first). With `advanced_search`, the smaller of `limit` and the selection's `page.size` applies, in the selection's own `sort` order. Omit to enrich the whole target. A `preview` is still capped at 100 companies. - `list_id` string: The list to enrich, identified by its Lists API id (e.g. `company_12345`). Mutually exclusive with `company_ids`. When supplied together with `advanced_search`, the search results are added to this list and then enriched (instead of enriching the list's current members). - `locale` string: Locale for AI-generated output. Defaults to `en-US`. - `output_type` 'ai_score' | 'ai_text' | 'ai_number' | 'ai_boolean' | 'contact_collection', required: The answer shape the AI produces. It is normally derived from the custom field, so it is only relevant (and required) for `preview` runs that name no `custom_field_id`. A preview that names a field takes its answer shape from the field; if it also sends an `output_type`, that value must equal the field's type, or the request is rejected with a 422 `invalid_parameter` error. This applies in both directions: a scalar `output_type` on a `contact_collection` field and `contact_collection` on a scalar AI field are both rejected. `ai_score`, `ai_text`, `ai_number` and `ai_boolean` run a scalar preview that returns `score` and `reason` per company. `contact_collection` runs a contacts preview that returns a `contacts` list per company; its settings come from the `contact_collection` object. - `prompt` string, required: Overrides the custom field's configured prompt for this run. For `contact_collection` fields the prompt is typically supplied here on each run, since the field stores no prompt. Required for every `preview` run, whether it names a custom field or not. - `use_external_data` boolean: Overrides the custom field's configured setting for whether the AI may use external data sources for this run. - object - `enrichment_strategy` 'preview', required: Which records to enrich - `advanced_search` object: A set of companies selected by an advanced search query, instead of an explicit `company_ids` list. The companies matching `filters` are taken in `sort` order, limited to `page.size`, with any `excluded_company_ids` removed. - `excluded_company_ids` string[]: Company IDs to remove from the matched set (for example, rows the user deselected). Removed after the `page.size` limit is applied, so the final selection may be smaller than `page.size`. - `filters` object, required: Recursive filter tree applied to the company population. The root is always a `group` whose `items` are either individual filters or further `group` nodes (combined with `and`/`or`). The tree holds at most 50 filters and groups, the root included, and at most 5 levels of groups. - … - `page` object: Bounds how many of the matching companies are selected. - … - `sort` object: Ordering applied to the matching companies. Omit to use the default ordering. - … - `category` string: Overrides the custom field's configured prompt category for this run. - `company_ids` string[]: Specific company IDs to enrich. Mutually exclusive with `list_id` and `advanced_search`. - `contact_collection` object: Contact settings. On a run that names a `contact_collection` custom field they override the field's configuration for this run only. On a prompt-only preview with `output_type: contact_collection` there is no field, so they are the preview's settings. The object is always optional: a run that names a field falls back to the field's configuration, and a prompt-only preview falls back to the documented default for each setting. - `contacts_to_enrich` integer: Overrides how many of the collected contacts get their details revealed on this run. Defaults to `num_contacts_max_per_company`. - `enrich_emails` boolean: Whether email addresses are revealed for the enriched contacts. Must be present here or in the custom field's configuration, except on a prompt-only preview, which reveals nothing. - `enrich_phones` boolean: Whether phone numbers are revealed for the enriched contacts. Must be present here or in the custom field's configuration, except on a prompt-only preview, which reveals nothing. - `filter_groups` object: Restricts which contacts are collected within the targeted companies (by location, seniority, department and/or job-title keywords). When omitted, the custom field's saved contact filters apply; a prompt-only preview has no field, so no contact filter applies. - … - `find_more_contacts_details` boolean: Overrides whether details are revealed for the collected contacts on this run. - `num_contacts_max_per_company` integer: Overrides the maximum number of contacts collected per company for this run. Defaults to 10 when omitted, which is also the hard ceiling: a larger value is accepted but no run returns more than 10 contacts per company. - `custom_field_id` string, required: The API name of the custom field to enrich. Must be an AI field type (ai_score, ai_text, ai_number, ai_boolean) or a contact_collection field. Not required for `preview` runs, which dry-run a `prompt` instead of enriching a field; a preview that names one takes its answer shape from the field. - `limit` integer: Enrich only the first `limit` companies of the target. For `list_id` and `company_ids` they are taken in the list's default order (most complete records first). With `advanced_search`, the smaller of `limit` and the selection's `page.size` applies, in the selection's own `sort` order. Omit to enrich the whole target. A `preview` is still capped at 100 companies. - `list_id` string, required: The list to enrich, identified by its Lists API id (e.g. `company_12345`). Mutually exclusive with `company_ids`. When supplied together with `advanced_search`, the search results are added to this list and then enriched (instead of enriching the list's current members). - `locale` string: Locale for AI-generated output. Defaults to `en-US`. - `output_type` 'ai_score' | 'ai_text' | 'ai_number' | 'ai_boolean' | 'contact_collection': The answer shape the AI produces. It is normally derived from the custom field, so it is only relevant (and required) for `preview` runs that name no `custom_field_id`. A preview that names a field takes its answer shape from the field; if it also sends an `output_type`, that value must equal the field's type, or the request is rejected with a 422 `invalid_parameter` error. This applies in both directions: a scalar `output_type` on a `contact_collection` field and `contact_collection` on a scalar AI field are both rejected. `ai_score`, `ai_text`, `ai_number` and `ai_boolean` run a scalar preview that returns `score` and `reason` per company. `contact_collection` runs a contacts preview that returns a `contacts` list per company; its settings come from the `contact_collection` object. - `prompt` string, required: Overrides the custom field's configured prompt for this run. For `contact_collection` fields the prompt is typically supplied here on each run, since the field stores no prompt. Required for every `preview` run, whether it names a custom field or not. - `use_external_data` boolean: Overrides the custom field's configured setting for whether the AI may use external data sources for this run. - object - `enrichment_strategy` 'preview', required: Which records to enrich - `advanced_search` object, required: A set of companies selected by an advanced search query, instead of an explicit `company_ids` list. The companies matching `filters` are taken in `sort` order, limited to `page.size`, with any `excluded_company_ids` removed. - `excluded_company_ids` string[]: Company IDs to remove from the matched set (for example, rows the user deselected). Removed after the `page.size` limit is applied, so the final selection may be smaller than `page.size`. - `filters` object, required: Recursive filter tree applied to the company population. The root is always a `group` whose `items` are either individual filters or further `group` nodes (combined with `and`/`or`). The tree holds at most 50 filters and groups, the root included, and at most 5 levels of groups. - … - `page` object: Bounds how many of the matching companies are selected. - … - `sort` object: Ordering applied to the matching companies. Omit to use the default ordering. - … - `category` string: Overrides the custom field's configured prompt category for this run. - `company_ids` string[]: Specific company IDs to enrich. Mutually exclusive with `list_id` and `advanced_search`. - `contact_collection` object: Contact settings. On a run that names a `contact_collection` custom field they override the field's configuration for this run only. On a prompt-only preview with `output_type: contact_collection` there is no field, so they are the preview's settings. The object is always optional: a run that names a field falls back to the field's configuration, and a prompt-only preview falls back to the documented default for each setting. - `contacts_to_enrich` integer: Overrides how many of the collected contacts get their details revealed on this run. Defaults to `num_contacts_max_per_company`. - `enrich_emails` boolean: Whether email addresses are revealed for the enriched contacts. Must be present here or in the custom field's configuration, except on a prompt-only preview, which reveals nothing. - `enrich_phones` boolean: Whether phone numbers are revealed for the enriched contacts. Must be present here or in the custom field's configuration, except on a prompt-only preview, which reveals nothing. - `filter_groups` object: Restricts which contacts are collected within the targeted companies (by location, seniority, department and/or job-title keywords). When omitted, the custom field's saved contact filters apply; a prompt-only preview has no field, so no contact filter applies. - … - `find_more_contacts_details` boolean: Overrides whether details are revealed for the collected contacts on this run. - `num_contacts_max_per_company` integer: Overrides the maximum number of contacts collected per company for this run. Defaults to 10 when omitted, which is also the hard ceiling: a larger value is accepted but no run returns more than 10 contacts per company. - `custom_field_id` string, required: The API name of the custom field to enrich. Must be an AI field type (ai_score, ai_text, ai_number, ai_boolean) or a contact_collection field. Not required for `preview` runs, which dry-run a `prompt` instead of enriching a field; a preview that names one takes its answer shape from the field. - `limit` integer: Enrich only the first `limit` companies of the target. For `list_id` and `company_ids` they are taken in the list's default order (most complete records first). With `advanced_search`, the smaller of `limit` and the selection's `page.size` applies, in the selection's own `sort` order. Omit to enrich the whole target. A `preview` is still capped at 100 companies. - `list_id` string: The list to enrich, identified by its Lists API id (e.g. `company_12345`). Mutually exclusive with `company_ids`. When supplied together with `advanced_search`, the search results are added to this list and then enriched (instead of enriching the list's current members). - `locale` string: Locale for AI-generated output. Defaults to `en-US`. - `output_type` 'ai_score' | 'ai_text' | 'ai_number' | 'ai_boolean' | 'contact_collection': The answer shape the AI produces. It is normally derived from the custom field, so it is only relevant (and required) for `preview` runs that name no `custom_field_id`. A preview that names a field takes its answer shape from the field; if it also sends an `output_type`, that value must equal the field's type, or the request is rejected with a 422 `invalid_parameter` error. This applies in both directions: a scalar `output_type` on a `contact_collection` field and `contact_collection` on a scalar AI field are both rejected. `ai_score`, `ai_text`, `ai_number` and `ai_boolean` run a scalar preview that returns `score` and `reason` per company. `contact_collection` runs a contacts preview that returns a `contacts` list per company; its settings come from the `contact_collection` object. - `prompt` string, required: Overrides the custom field's configured prompt for this run. For `contact_collection` fields the prompt is typically supplied here on each run, since the field stores no prompt. Required for every `preview` run, whether it names a custom field or not. - `use_external_data` boolean: Overrides the custom field's configured setting for whether the AI may use external data sources for this run. - `type` string ## Response `202` Job accepted and started - object - `data` EnrichmentJobV1, required - `attributes` object, required - `completed_at` string, date-time, nullable: When the job finished. Present only once the job has reached `completed` or `failed`. - `configuration` object: The settings the job was created with: `custom_field_id`, `enrichment_strategy`, `company_ids`, `list_id` and `advanced_search`, each when it was sent. The response that creates the job has no `configuration`. - `advanced_search` object: A set of companies selected by an advanced search query, instead of an explicit `company_ids` list. The companies matching `filters` are taken in `sort` order, limited to `page.size`, with any `excluded_company_ids` removed. - `excluded_company_ids` string[]: Company IDs to remove from the matched set (for example, rows the user deselected). Removed after the `page.size` limit is applied, so the final selection may be smaller than `page.size`. - `filters` object, required: Recursive filter tree applied to the company population. The root is always a `group` whose `items` are either individual filters or further `group` nodes (combined with `and`/`or`). The tree holds at most 50 filters and groups, the root included, and at most 5 levels of groups. - `items` CompaniesAdvancedSearchFilterItem[], required: Nested filter conditions or sub-groups. Each item is either a `filter` or a nested `group`. An empty list matches every company. - … - `operator` 'and' | 'or', required: The logical operator combining the items. - `type` 'group', required: Indicates this is the root filter group. - `page` object: Bounds how many of the matching companies are selected. - `size` integer: Maximum number of matching companies to select, taken in `sort` order. Omit to select every match, up to the endpoint's per-job maximum. - `sort` object: Ordering applied to the matching companies. Omit to use the default ordering. - `direction` 'asc' | 'desc': Sort direction. Defaults to `asc`. - `field` string: Comma-separated list of company attributes to sort by, applied in order (e.g. `employee_count,name`). Allowed values: `relevance`, `name`, `employee_count`, `revenue`, `founded_year`. Unknown values are rejected with `invalid_parameter`. - `company_ids` string[]: Specific company IDs targeted (mutually exclusive with list_id) - `custom_field_id` string: The custom field being enriched - `enrichment_strategy` 'missing_values' | 'all' | 'preview': Which records to enrich - `list_id` string: The `list_id` the job was created with. - `created_at` string, date-time, required: When the job was created - `credits` object: Credit consumption details - `consumed` number: Credits consumed so far. Some job types are priced per record at a fractional rate, so this can be a decimal. - `estimated` number: Credits estimated for the job. Some job types are priced per record at a fractional rate, so this can be a decimal. - `errors` object[]: Present only when status is `failed`. When a job created from a search selection fails because the search rejected its filters or sort, or failed itself, it holds the search's own code and title, such as `invalid_filters` or `server_timeout`. - `code` string, required: Machine-readable error code - `title` string, required: Human-readable error description - `results` object[]: Per-company results. Present only for completed `preview` runs; regular runs write their values to the custom field instead. A scalar preview returns `score` and `reason`; a contacts preview (of a `contact_collection` field, or a prompt-only preview with `output_type: contact_collection`) returns `contacts` instead. - `company_id` string, required: The company the result is for - `company_name` string, nullable, required: The company's name, on every preview result. `null` when no name is known for the company. On a contacts preview it is truncated so that its JSON-encoded form is at most 40 bytes, not counting the enclosing quotes. On a contacts preview, an account without the `target` entitlement gets the name masked: its first three characters followed by one `*` per remaining character, as in company search results. - `contacts` ContactPreviewV1[]: The contacts the AI selected for this company. Present only on a contacts preview, in place of `score` and `reason`. When the AI finds no contacts for a company, the array is empty and `outcome` is still `success`. Contact details are not revealed by a preview, so only the identifying fields of each contact are returned. - `attributes` object, required - `full_name` string, nullable, required: The contact's display name. `null` when the source has none. - `position` object, nullable, required: The contact's position within the company. `null` when the contact has no known job title; otherwise `title` is always a string. - … - `id` string, required: The Leadfeeder contact ID. - `type` 'contact_preview', required: The type of the object. A preview carries a subset of the contact resource, so it has its own type. - `outcome` 'success' | 'no_data', required: Whether the AI produced an answer for this company - `reason` string: The AI's explanation for the answer - `score` unknown - `status` 'running' | 'completed' | 'failed', required: Current status of the job - `summary` object: Record processing summary - `failed` integer: Records that failed enrichment - `succeeded` integer: Records enriched successfully - `total` integer: Total records to process - `id` string, required: Unique job identifier - `type` string, required - `meta` object, required - `request_id` string, required: A unique identifier assigned to each API request for end-to-end traceability. ## Other responses - `400`: The request body is missing, isn't valid JSON or isn't a JSON object, or its `data` isn't an object with an `attributes` object (`invalid_request_body`). An attribute this endpoint doesn't take gives `unknown_attributes`. - `401`: Unauthorized. The request was rejected because the credentials are missing, invalid, expired, or have been revoked. The client must re-authenticate before retrying. Clients can differentiate via the `code` value of the first item in `errors`. - `403`: Forbidden. The credentials are valid but the caller is not authorized to perform the request — typically because the user lacks the required permission, the OAuth scope is insufficient, the subscription plan does not include the required entitlement, the `account_id` does not belong to the authenticated user, or the target list is read-only and its members cannot be modified. Clients can differentiate via the `code` value of the first item in `errors`. - `404`: Custom field not found - `422`: The request body is valid JSON but breaks a rule. The error's title names each broken rule as the attribute's path followed by the rule, such as `custom_field_id is missing`, joined with `; ` when there are several. Its code is `missing_mandatory_fields` if any attribute is missing or empty, and `invalid_parameter` otherwise. A prompt saved on the custom field that is longer than 16,000 characters gives `unprocessable_content`. - `429`: Too many requests. Either the per-second rate limit or the monthly quota configured for the API key / OAuth application has been exceeded. Clients can differentiate via the `code` value of the first item in `errors`. - `500`: Internal server error ## Changes > 46 revisions in range; 1 not diffed. - **2026-11-03** `686d4e39eb05`: 1 info - added the optional property `data/attributes/configuration/advanced_search` to the response with the `202` status - **2026-10-29** `78e7c2a33afa`: 1 info - added the new optional request property `data/attributes/limit` - **2026-10-23** `cfe89c1fc59d`: 1 breaking - the `data/attributes/credits/consumed` response's property type changed from `integer` to `number` for status `202` - **2026-10-21** `a1970eac18e7`: 6 info - added `subschema #3` to the `data/attributes` request property `anyOf` list - added the new `contact_collection` enum value to the request property `data/attributes/output_type` - added the optional property `data/attributes/results/items/contacts` to the response with the `202` status - the response property `data/attributes/results/items/company_id` became required for the status `202` - …2 more - **2026-10-06** `69e0c94ac1fd`: 1 info - added the new optional request property `data/attributes/advanced_search/allOf[subschema #1]/filters/items/items/oneOf[subschema #5: Geo Filter]/label` [Operation history](https://skmtc.dev/leadfeeder/apis/leadfeeder-public-api/changes/v1/companies/enrichment-jobs/post.md) --- [API](https://skmtc.dev/leadfeeder/apis/leadfeeder-public-api.md) - [All operations](https://skmtc.dev/leadfeeder/apis/leadfeeder-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/leadfeeder/apis/leadfeeder-public-api/revisions/686d4e39eb05?raw)