---
title: "Estimate Company Enrichment Job"
method: POST
path: "/v1/companies/enrichment-jobs/estimate"
tags: ["Companies", "Enrichment", "v1"]
---

# Estimate Company Enrichment Job

`POST /v1/companies/enrichment-jobs/estimate`

## Request

- Base URL: `https://api.leadfeeder.com`
- URL: `https://api.leadfeeder.com/v1/companies/enrichment-jobs/estimate`
- 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`

Estimate the credit cost for enriching companies with AI-generated custom field values. Target the estimate with a specific `list_id`, flat `company_ids`, or a pre-computed `company_count`.
Credit Note: This endpoint does not consume credits.

:::info
Requires the `companies:read` OAuth2 scope.
:::

## Query parameters

- `account_id` string, required

## Request body

- object
  - `data` object, required
    - `attributes` union, required: Provide a `custom_field_id` plus the target to size the estimate: `list_id`, `company_ids`, or a pre-computed `company_count`.
      - object
        - `company_count` integer, required: Pre-computed number of companies to enrich, up to the 50,000 per-job maximum. When provided, the estimate uses this value directly and skips resolving the target, so `list_id` / `company_ids` may be omitted.
        - `company_ids` string[]: Specific company IDs to size the estimate.
        - `contact_collection` object: Overrides that only apply when `custom_field_id` is a `contact_collection` field — they shape the reveal portion of the estimate.
          - `contacts_to_enrich` integer: Overrides how many contacts per company get their details revealed, which drives the reveal portion of the estimate. Defaults to the custom field's configured maximum contacts per company.
          - `enrich_emails` boolean: Whether email reveals are included in the estimate. Must be present here or in the custom field's configuration.
          - `enrich_phones` boolean: Whether phone reveals are included in the estimate. Must be present here or in the custom field's configuration.
        - `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.
        - `enrichment_strategy` 'missing_values' | 'all': Which records to enrich. Defaults to `all` when omitted. `preview` applies to job creation only, not to estimates.
        - `limit` integer: Size the estimate for a job that enriches only the first `limit` companies of the target, as `limit` does on job creation. The estimate covers the smaller of `limit` and the target's size (or `company_count`, when provided).
        - `list_id` string: The list to size the estimate, identified by its Lists API id (e.g. `company_12345`).
        - `prompt` string: The prompt the run will use, when it overrides the custom field's configured prompt. Without it the estimate uses the field's prompt. For `contact_collection` fields the prompt is typically supplied here, since the field stores no prompt, so pass the same prompt the create request will use. A `contact_collection` estimate that resolves no prompt runs no model, so `estimated_total_credits` includes no AI cost, only contact reveals.
      - object
        - `company_count` integer: Pre-computed number of companies to enrich, up to the 50,000 per-job maximum. When provided, the estimate uses this value directly and skips resolving the target, so `list_id` / `company_ids` may be omitted.
        - `company_ids` string[], required: Specific company IDs to size the estimate.
        - `contact_collection` object: Overrides that only apply when `custom_field_id` is a `contact_collection` field — they shape the reveal portion of the estimate.
          - `contacts_to_enrich` integer: Overrides how many contacts per company get their details revealed, which drives the reveal portion of the estimate. Defaults to the custom field's configured maximum contacts per company.
          - `enrich_emails` boolean: Whether email reveals are included in the estimate. Must be present here or in the custom field's configuration.
          - `enrich_phones` boolean: Whether phone reveals are included in the estimate. Must be present here or in the custom field's configuration.
        - `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.
        - `enrichment_strategy` 'missing_values' | 'all': Which records to enrich. Defaults to `all` when omitted. `preview` applies to job creation only, not to estimates.
        - `limit` integer: Size the estimate for a job that enriches only the first `limit` companies of the target, as `limit` does on job creation. The estimate covers the smaller of `limit` and the target's size (or `company_count`, when provided).
        - `list_id` string: The list to size the estimate, identified by its Lists API id (e.g. `company_12345`).
        - `prompt` string: The prompt the run will use, when it overrides the custom field's configured prompt. Without it the estimate uses the field's prompt. For `contact_collection` fields the prompt is typically supplied here, since the field stores no prompt, so pass the same prompt the create request will use. A `contact_collection` estimate that resolves no prompt runs no model, so `estimated_total_credits` includes no AI cost, only contact reveals.
      - object
        - `company_count` integer: Pre-computed number of companies to enrich, up to the 50,000 per-job maximum. When provided, the estimate uses this value directly and skips resolving the target, so `list_id` / `company_ids` may be omitted.
        - `company_ids` string[]: Specific company IDs to size the estimate.
        - `contact_collection` object: Overrides that only apply when `custom_field_id` is a `contact_collection` field — they shape the reveal portion of the estimate.
          - `contacts_to_enrich` integer: Overrides how many contacts per company get their details revealed, which drives the reveal portion of the estimate. Defaults to the custom field's configured maximum contacts per company.
          - `enrich_emails` boolean: Whether email reveals are included in the estimate. Must be present here or in the custom field's configuration.
          - `enrich_phones` boolean: Whether phone reveals are included in the estimate. Must be present here or in the custom field's configuration.
        - `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.
        - `enrichment_strategy` 'missing_values' | 'all': Which records to enrich. Defaults to `all` when omitted. `preview` applies to job creation only, not to estimates.
        - `limit` integer: Size the estimate for a job that enriches only the first `limit` companies of the target, as `limit` does on job creation. The estimate covers the smaller of `limit` and the target's size (or `company_count`, when provided).
        - `list_id` string, required: The list to size the estimate, identified by its Lists API id (e.g. `company_12345`).
        - `prompt` string: The prompt the run will use, when it overrides the custom field's configured prompt. Without it the estimate uses the field's prompt. For `contact_collection` fields the prompt is typically supplied here, since the field stores no prompt, so pass the same prompt the create request will use. A `contact_collection` estimate that resolves no prompt runs no model, so `estimated_total_credits` includes no AI cost, only contact reveals.
    - `type` string

## Response `200`

Estimate calculated successfully

- object
  - `data` object, required
    - `attributes` object, required
      - `company_count` integer, required: Number of companies that would be enriched
      - `estimated_total_credits` number, required: Estimated credits that would be consumed. AI enrichment is priced per company at a fractional rate, so this can be a decimal.
    - `id` string, uuid, required: Unique estimate 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`: Invalid request body envelope
- `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`: Unprocessable content — request body is well-formed but fails domain validation
- `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-10-29** `78e7c2a33afa`: 1 info
  - added the new optional request property `data/attributes/limit`
- **2026-10-28** `65f4fa41d7c2`: 1 info
  - added the new optional request property `data/attributes/prompt`
- **2026-10-23** `cfe89c1fc59d`: 1 breaking
  - the `data/attributes/estimated_total_credits` response's property type changed from `integer` to `number` for status `200`
- **2026-09-03** `ac752c6c2be0`: 7 info
  - added the optional property `errors/items/source` to the response with the `400` status
  - added the optional property `errors/items/source` to the response with the `401` status
  - added the optional property `errors/items/source` to the response with the `403` status
  - added the optional property `errors/items/source` to the response with the `404` status
  - …3 more
- **2026-08-26** `4ea7746e6533`: 2 info
  - added the new optional request property `data/attributes/contact_collection`
  - the `enrichment_strategy` request property default value `all` was added

[Operation history](https://skmtc.dev/leadfeeder/apis/leadfeeder-public-api/changes/v1/companies/enrichment-jobs/estimate/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)