Create Company Enrichment Job

POST

/v1/companies/enrichment-jobs

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. contact_collection fields cannot be previewed.
Credit Note: Credits are consumed as companies are enriched.

INFO

Requires the companies:read OAuth2 scope.

Request

Authorization

API Key

Add parameter in header

X-Api-Key

Example:

X-Api-Key: ********************

or

Query Params

Body Params application/jsonRequired

Examples

Target companies matching a searchSave search results to a list, then enrich themTarget specific companiesTarget entire listCollect contacts for a list, with a per-run promptDry-run a prompt against a sample (nothing is written)

{
    "data": {
        "attributes": {
            "advanced_search": {
                "filters": {
                    "items": [
                        {
                            "field": "country_code",
                            "operator": "in",
                            "type": "filter",
                            "value": [
                                "DE"
                            ]
                        }
                    ],
                    "operator": "and",
                    "type": "group"
                },
                "page": {
                    "size": 1000
                },
                "sort": {
                    "direction": "desc",
                    "field": "employee_count"
                }
            },
            "custom_field_id": "ai_account_score",
            "enrichment_strategy": "all"
        },
        "type": "enrichment_job"
    }
}

Request Code Samples

Shell

JavaScript

Java

Swift

Go

PHP

Python

HTTP

C

C#

Objective-C

Ruby

OCaml

Dart

R

cURL

Target companies matching a searchSave search results to a list, then enrich themTarget specific companiesTarget entire listCollect contacts for a list, with a per-run promptDry-run a prompt against a sample (nothing is written)

curl --location 'https://api.leadfeeder.com/v1/companies/enrichment-jobs?account_id=123456' \
--header 'X-Api-Key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "data": {
        "attributes": {
            "advanced_search": {
                "filters": {
                    "items": [
                        {
                            "field": "country_code",
                            "operator": "in",
                            "type": "filter",
                            "value": [
                                "DE"
                            ]
                        }
                    ],
                    "operator": "and",
                    "type": "group"
                },
                "page": {
                    "size": 1000
                },
                "sort": {
                    "direction": "desc",
                    "field": "employee_count"
                }
            },
            "custom_field_id": "ai_account_score",
            "enrichment_strategy": "all"
        },
        "type": "enrichment_job"
    }
}'

Responses

🟢202Accepted

application/json

Job accepted and started

Bodyapplication/json

Example

{
    "data": {
        "attributes": {
            "created_at": "2026-03-10T12:00:00Z",
            "status": "running"
        },
        "id": "job_21662",
        "type": "enrichment_job"
    },
    "meta": {
        "request_id": "cf054205-dd8c-4473-8689-07c30fe0789f"
    }
}

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠404Record Not Found

🟠422Parameter Error

🟠429Server Error

🔴500Server Error

Modified at 2026-09-17 07:46:23

Get Company Details

Estimate Company Enrichment Job