Leadfeeder

Create a new tag with the provided attributes. This endpoint allows clients to define a new tag that can be assigned to companies. The response returns the full tag object, including its generated identifier and timestamps. Credit Note: Creating tags doe not consume credits. :::info Requires the `tags:write` OAuth2 scope. :::

create_tag

Create a buyer persona — a named, saved set of contact-level filter criteria — for the given account. Call `get_buyer_personas` first and reuse an existing persona that already expresses what the user wants rather than creating a near-duplicate. Confirm the name and the filters with the user before creating. The body lives under `data.attributes`. `filters` groups criteria by category: `department`, `seniority`, `job_title` and `location`. At least one category must be present and non-empty — omit a category rather than sending it as an empty array. Every entry needs a `search_value` (the value matched on) and may carry a `display_value` (its human-readable label, defaulting to `search_value`) and `negated: true` to exclude rather than include. `department` and `seniority` take one of a fixed set of codes, and an invalid one is rejected with a 422 naming the accepted values — note seniority has only three (`top_management`, `middle_management`, `employees`), so map job levels onto those rather than inventing a code. `job_title` is free text matched against the contact's title. `location` depends on that entry's `type`, which defaults to `country_code` (an ISO 3166-1 alpha-2 code like "DE").

create_buyer_persona

Create a new custom feed (a saved, filtered view of web-visiting companies) for the given account. The body lives under `data.attributes`; `name` (max 60 chars) is required. `advanced_filters` is NOT a free-form tree. It has a FIXED shape and any deviation returns `422 invalid_filters`. Build it exactly like this: - The root is always `{ "type": "group", "operator": "and" }` (never add `negated` to the root). - The root `items` array has EXACTLY TWO entries, in order: `[0]` the INCLUDE bucket `{ "type": "group", "operator": "or" }` and `[1]` the EXCLUDE bucket `{ "type": "group", "operator": "or", "negated": true }`. The exclude bucket is MANDATORY even when you exclude nothing — send it with `"items": []`. (Most 422s are caused by omitting this second bucket or forgetting its `"negated": true`.) - Inside a bucket, each `items` entry is an AND row `{ "type": "group", "operator": "and" }`. - Inside an AND row, each `items` entry is an OR group `{ "type": "group", "operator": "or" }`. - Inside an OR group, each `items` entry is a leaf `{ "type": "filter", "field", "operator", "value", "display_value" }`. So the nesting is always `and → [or(include), or(exclude, negated)] → and → or → filter`. Put values for the SAME field in one OR group; AND across different fields by using separate OR groups in the same AND row. Minimal valid body — companies from Germany (`country_code = DE`) with an empty exclude bucket. Copy this shape and swap in your own conditions: ```json { "data": { "type": "custom_feed", "attributes": { "name": "DE companies", "advanced_filters": { "type": "group", "operator": "and", "items": [ { "type": "group", "operator": "or", "items": [ { "type": "group", "operator": "and", "items": [ { "type": "group", "operator": "or", "items": [ { "type": "filter", "field": "country_code", "operator": "is", "value": "DE", "display_value": "Germany" } ] } ] } ] }, { "type": "group", "operator": "or", "negated": true, "items": [] } ] } } } } ``` Field/operator/value rules are field-specific: numeric fields like `employee_count` use `at_least` / `less_than` with an integer value; string fields like `country_code` or `region` use `is` / `is_not`; URL/text fields like `page_url` use `contains` / `begins_with`. Use ISO codes for `country_code` (e.g. "DE") and put the readable name in `display_value` (e.g. "Germany"). Not every operator is valid for every field — an unsupported pairing also returns `422`. For the full list of fields and the operators/value formats each accepts, see https://docs.leadfeeder.com/api/public/custom-feed-filter-reference-363484m0

create_web_visits_custom_feed

Create a goal — a named page-view condition that marks the page views signalling buying intent, such as visits to a pricing or demo page — for the given account. Call `get_web_visits_goals` first and reuse a goal that already covers what the user wants rather than creating a near-duplicate. Confirm the name and the condition with the user before creating: goals are shared by everyone in the account. The body lives under `data.attributes`: `name` and `criterion` are required, `enabled` defaults to true. `criterion` has a `field`, an `operator` and a `value`. For a page, prefer `page_url` with `contains` and a distinctive part of the path, e.g. "/pricing"; `page` matches the page title instead. `form_submit` matches the URL of the page a form was submitted on, or any form with `is_present`. Operators are field-specific — `contains` works on `page_url`, `page`, `file_download_name` and `video_title`; `is_present` / `is_empty` work on `form_submit`, `file_download_name`, `video_title` and `video_url` and take no `value`. The tool schema lists the operators each `field` accepts, and a pairing it does not list fails as invalid arguments. A pattern with nothing but "/" or "*" returns a 422 saying what is accepted. Tell the user a new goal is not retroactive: it only marks page views tracked from now on.

create_web_visits_goal

Create a new list in the account. :::info Requires the `lists:write` OAuth2 scope. :::

create_list

Create an Ideal Customer Profile (ICP) — a named, saved set of company-level filter criteria — for the given account. Call `get_icps` first and reuse an existing ICP that already expresses what the user wants rather than creating a near-duplicate. Confirm the name and the filters with the user before creating. The body lives under `data.attributes`. `filters` groups criteria by category: `industries`, `employee_count` and `location`. At least one category must be present and non-empty — omit a category rather than sending it as an empty array. Every entry needs a `search_value` (the value matched on) and may carry a `display_value` (its human-readable label, defaulting to `search_value`) and `negated: true` to exclude rather than include. `search_value` is a code, not free text, and an invalid one is rejected with a 422 naming the accepted values. For `industries` it is an industry code such as "1594.6.4" (Software Development) — the same code a company's `industries.industry[].code` returns, and one of those returned by the `Get Industries` endpoint (`GET /v1/industries`). Take it from there or from an existing ICP via `get_icps`; do not guess. For `employee_count` it is one of "1-10", "11-100", "101-500", "501-1000", "1001-5000", "5001-10000" or "10001", with "10001" meaning "10000+". For `location` it depends on that entry's `type`, which defaults to `country_code` (an ISO 3166-1 alpha-2 code like "DE").

create_icp

CONFIRMATION REQUIRED — the server enforces approval for this tool, so do NOT ask the user before calling it. Call it with the parameters you need: it will NOT execute. The server replies with a `confirmation_required` response naming the exact action, plus a `confirm_token` in `data`. Show that action to the user and, only if they approve, call again with identical parameters plus the token. Delete a custom field from the account. Once removed, the custom field will no longer be accessible. Credit Note: Deleting custom fields does not consume credits. :::info Requires the `custom_fields:write` OAuth2 scope. :::

delete_custom_field

CONFIRMATION REQUIRED — the server enforces approval for this tool, so do NOT ask the user before calling it. Call it with the parameters you need: it will NOT execute. The server replies with a `confirmation_required` response naming the exact action, plus a `confirm_token` in `data`. Show that action to the user and, only if they approve, call again with identical parameters plus the token. Delete a list from the account. Once removed, the list will no longer be accessible. Credit Note: Deleting list does not consume credits. :::info Requires the `lists:write` OAuth2 scope. :::

delete_list

CONFIRMATION REQUIRED — the server enforces approval for this tool, so do NOT ask the user before calling it. Call it with the parameters you need: it will NOT execute. The server replies with a `confirmation_required` response naming the exact action, plus a `confirm_token` in `data`. Show that action to the user and, only if they approve, call again with identical parameters plus the token. Delete a specific tag identified by its ID Removes the tag from the account and unassigns it from all associated companies. Once deleted, the tag cannot be recovered. Credit Note: Deleting tags does not consume credits. :::info Requires the `tags:write` OAuth2 scope. :::

delete_tag

Delete a buyer persona by its ID. Confirm with the user before calling this — it removes something other people in the account may be using, and it cannot be undone.

delete_buyer_persona

CONFIRMATION REQUIRED — the server enforces approval for this tool, so do NOT ask the user before calling it. Call it with the parameters you need: it will NOT execute. The server replies with a `confirmation_required` response naming the exact action, plus a `confirm_token` in `data`. Show that action to the user and, only if they approve, call again with identical parameters plus the token. Delete a custom feed by its ID. :::info Requires the `web_visits:write` OAuth2 scope. :::

delete_web_visits_custom_feed

CONFIRMATION REQUIRED — the server enforces approval for this tool, so do NOT ask the user before calling it. Call it with the parameters you need: it will NOT execute. The server replies with a `confirmation_required` response naming the exact action, plus a `confirm_token` in `data`. Show that action to the user and, only if they approve, call again with identical parameters plus the token. Delete a goal by its ID. This also deletes the goal's custom feed and removes the goal from the page views it marked. Confirm with the user before calling this — it removes something other people in the account may be using, and it cannot be undone. The deletion completes in the background, so the goal may still be listed for a short time afterwards. Do not call this again or report a failure because of that.

delete_web_visits_goal

Delete an Ideal Customer Profile (ICP) by its ID. This also deletes the custom feed that surfaced the companies matching it. Confirm with the user before calling this — it removes something other people in the account may be using, and it cannot be undone.

delete_icp

Enriches an input IP (IPv4/IPv6) with matching company information (if any). Subscription required: This tool requires an active IP Enrich subscription. If the account does not have this subscription, every call returns `403 access_denied`. Do not retry — contact Leadfeeder support to activate the subscription. Monthly call limit: The account has a monthly call limit set by its subscription tier. The limit is checked before the lookup executes; once reached, calls return `403 api_usage_limit_exceeded` for the rest of the month. Only successful calls count toward the limit — failed ones (invalid IP, no company found) do not. The limit resets at the start of each calendar month. No credits consumed: This tool does not use Leadfeeder credits. It uses a separate quota called matches, defined by the account's IP Enrich subscription tier. If a company was resolved from the IP (i.e. `company_type` is `"company"` in the response), `meta.num_results` is `1` and the call counts against the monthly limit. If the IP belongs to a network or ISP instead (`"shared_network"` in the response), `meta.num_results` is `0` and the call does not count.

enrich_ip

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. :::

estimate_company_enrichment_job

Estimate the credit cost for enriching contacts with email and phone data. Accepts either explicit `contact_ids` or a `list_id` to target an entire list. Returns the number of eligible contacts and the estimated total credits that would be consumed. Credit Note: This endpoint does not consume credits. :::info Requires the `contacts:read` OAuth2 scope. :::

estimate_find_contact_data_job

Retrieve the status of a batch add-tags job created via `POST /v1/tags/batch-add-tags-jobs`. While `status` is `running`, `summary` is omitted. Once `status` becomes `completed`, `summary` carries the outcome counts (including `failed_count`). On `failed`, `errors` describes the failure. Credit Note: This endpoint does not consume credits. :::info Requires the `companies:read` OAuth2 scope. :::

get_batch_add_tags_job

Retrieve the status of a batch add-to-list job created via `POST /v1/lists/batch-add-to-list-jobs`. While `status` is `running`, `results` and `summary` are omitted. Once `status` becomes `completed`, `results` carries the per-item outcome and `summary` carries the per-outcome counts (including `failed_count`) together with `list_size_before` and `list_size_after`. A job created from a search selection reports `summary` counts only — no per-item `results`. On `failed`, `errors` describes the failure. Jobs are kept for 7 days after creation. Credit Note: This endpoint does not consume credits. :::info Requires the `lists:read` OAuth2 scope. :::

get_batch_add_to_list_job

Retrieve the status of a batch remove-tags job created via `POST /v1/tags/batch-remove-tags-jobs`. While `status` is `running`, `summary` is omitted. Once `status` becomes `completed`, `summary` carries the outcome counts (including `failed_count`). On `failed`, `errors` describes the failure. Credit Note: This endpoint does not consume credits. :::info Requires the `companies:read` OAuth2 scope. :::

get_batch_remove_tags_job

Retrieve the status of a batch remove-from-list job created via `POST /v1/lists/batch-remove-from-list-jobs`. While `status` is `running`, `results` and `summary` are omitted. Once `status` becomes `completed`, `results` carries the per-item outcome and `summary` carries the per-outcome counts (including `failed_count`) together with `list_size_after`. A job created from an `advanced_search` selection reports `summary` counts only — no per-item `results`. On `failed`, `errors` describes the failure. Credit Note: This endpoint does not consume credits. :::info Requires the `lists:read` OAuth2 scope. :::

get_batch_remove_from_list_job

Get the details of a specific buyer persona by ID, including its name, creation timestamp, and the full set of filter criteria that define it. Credit Note: Retrieving a buyer persona definition does not consume credits. :::info Requires the `buyer_personas:read` OAuth2 scope. :::

get_buyer_persona

Fetch detailed information about a specific campaign using its campaign ID. Use the include parameter to attach related campaign data, campaign settings, list, or custom feed information to the result. :::info Requires the `campaigns:read` OAuth2 scope. :::

get_campaign

CONFIRMATION REQUIRED — the server enforces approval for this tool, so do NOT ask the user before calling it. This tool MAY consume Leadfeeder credits. Call it with the parameters you need: it will NOT execute. The server replies with a `confirmation_required` response naming the exact action, plus a `confirm_token` in `data`. Show that action to the user and, only if they approve, call again with identical parameters plus the token. Fetch detailed information about a specific company, including firmographics and hierarchy information based on the provided Leadfeeder company_id. Credit Note: Accessing full deep data consumes 1 credit, unless the company was already accessed within the last 12 months. :::info Requires the `companies:read` OAuth2 scope. :::

get_company

Retrieve the current status of a Company AI Enrichment job. Returns progress counters, credit consumption, and any errors. Jobs are retained for 7 days after completion. Credit Note: This endpoint does not consume credits. :::info Requires the `companies:read` OAuth2 scope. :::

get_company_enrichment_job

CRITICAL: CREDIT-CONSUMING TOOL Using this tool MAY consume Leadfeeder credits. You MUST follow this protocol: 1. PAUSE: Do not execute this tool automatically. 2. INFORM: Tell the user this action may consume credits. It is not possible to know upfront how many credits will be consumed (if any). The actual consumption will be determined during execution. 3. CONFIRM: Ask the user for an explicit Yes/No confirmation to proceed. 4. EXECUTE: Only call this tool after receiving clear, affirmative consent. Get the details of a contact by ID. Credit Note: Accessing full deep data consumes 1 credit, unless the contact was already accessed within the last 12 months. :::info Requires the `contacts:read` OAuth2 scope. :::

get_contact

Returns the account's cookie consent management state. :::info Requires the `accounts:read` OAuth2 scope. :::

get_cookie_consent_settings

Returns the full list of countries with their administrative regions. Credit Note: This endpoint does not consume credits. :::info Requires the `companies:read` OAuth2 scope. :::

get_countries

Retrieves the identity of the current API user - a "whoami" endpoint. Unlike most endpoints, this one does not require the `account_id` query parameter — the user's identity is independent of the account they are currently working on.

get_current_user_info

Retrieve a single custom feed by its ID. :::info Requires the `web_visits:read` OAuth2 scope. :::

get_web_visits_custom_feed

Fetch the details of a specific custom field using its internal name. The response returns the field's attributes. Credit Note: Retrieving custom field definitions does not consume credits. :::info Requires the `custom_fields:read` OAuth2 scope. :::

get_custom_field

Returns the current "Allow third-party providers" state for the account and its full change history, ordered most-recent-first. Each changelog entry records what was set, who set it, and when. :::info Requires the `accounts:read` OAuth2 scope. :::

get_data_processing_settings

Access usage statistics for various API endpoints for monitoring and auditing purposes. Returns usage data for all endpoints accessible by the requesting account within the specified date range. :::info Requires the `usage:read` OAuth2 scope. :::

usage

Retrieve the current status of a Find Contact Data job. Returns progress counters, credit consumption, and any errors. Jobs are retained for 7 days after completion. Credit Note: This endpoint does not consume credits. :::info Requires the `contacts:read` OAuth2 scope. :::

get_find_contact_data_job

Resolves a typed city name or postal code into geographic coordinates. The returned `latitude` / `longitude` can be used to populate the `value.lat` / `value.lon` of the Geo Filter (`field: geo`, `operator: within`). Results can be scoped to one or more countries via `country_codes`, and `search_fields` limits which address fields the text may match; when omitted, both cities and postal codes are searched. Credit Note: This endpoint does not consume credits. :::info Requires the `companies:read` OAuth2 scope. :::

get_geo_suggestions

Get a goal by its ID, including its name, whether it is enabled and the page-view condition that defines it. Credit Note: Retrieving a goal does not consume credits. :::info Requires the `web_visits:read` OAuth2 scope. :::

get_web_visits_goal

Get the details of a specific Ideal Customer Profile (ICP) by ID, including its name, creation timestamp, and the full set of filter criteria that define it. `relationships.custom_feed` links the ICP to the Web Visits custom feed created alongside it, which lists the visiting companies matching the ICP; it is `null` for the few ICPs that have no feed. Credit Note: Retrieving an ICP definition does not consume credits. :::info Requires the `icps:read` OAuth2 scope. :::

get_icp

Returns the full list of industries based on the provided industry classification. Credit Note: This endpoint does not consume credits. :::info Requires the `companies:read` OAuth2 scope. :::

get_industries

Retrieve the details of a specific list using its unique ID. The response includes the list's attributes, such as its name and scope, along with any related information requested through query parameters. This endpoint is used to fetch the full definition of a list before viewing, updating, or managing its assigned items. Credit Note: Retrieving list definitions does not consume credits. :::info Requires the `lists:read` OAuth2 scope. :::

get_list

Fetch the details of a specific tag using its unique tag ID. Returns the tag’s attributes, including its name, color, and timestamps indicating when it was created and last updated. Credit Note: Retrieving tag data does not consume credits. :::info Requires the `tags:read` OAuth2 scope. :::

get_tag

Lists every Leadfeeder account available to this API key. Use this tool whenever you need to list, get, show, or choose accounts. get_account_info IS the list-accounts tool: there is NO get_accounts, list_accounts, or accounts tool, so never invent or call another name — always call get_account_info. Call with no account_id to list all accounts; each result includes the account name and id, but no credit details. Call with a specific account_id to retrieve that one account's credit details. Credits come back as account-wide totals (available, used, remaining) plus a credits_pools breakdown, one entry per pool: a recurring pool for the subscription credits, which renew on renews_at, and a one_off pool for extra credits bought on top, which are forfeited on expires_at. When the user asks how many credits they have left or when those credits run out, read credits_pools rather than the totals, since the pools run out on different dates. A pool the account was granted no credits in is not listed at all, so the pools can add up to less than the totals. Other pool types may appear; report them as-is. Every account also carries the company it belongs to under relationships.account_company, as an id only. Pass include=account_company to load that company's name as well — do this whenever you need to name or group accounts by their company, since the id alone is not meaningful to the user.

get_account_info