Leadfeeder

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 new list in the account. :::info Requires the `lists:write` OAuth2 scope. :::

create_list

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

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

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 custom feed by its ID. :::info Requires the `web_visits:write` OAuth2 scope. :::

delete_web_visits_custom_feed

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-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 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_add_to_list_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

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

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

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

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. Credit Note: Retrieving an ICP definition does not consume credits. :::info Requires the `icps:read` OAuth2 scope. :::

get_icp

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

Find matching companies based on the provided input parameters. Returns matching company IDs and basic company information. **Important:** Each company object must include at least one of these required fields: `company_name`, `url`, `vat_id`, or `register_id`. Additional fields like email, phone, and address can improve match accuracy but cannot be used alone. Credit Note: Matches do not consume credits. Credits are only used if you subsequently retrieve deep data for a company you haven't accessed within the last 12 months. :::info Requires the `companies:read` OAuth2 scope. :::

match_companies

Remove a single company from one or more lists. Best when you have one company and want it taken off several lists at once (company → many lists). WHEN NOT TO USE: If you are removing multiple companies from the same list, do NOT call this tool in a loop — use Create Batch Remove from List Job (create_batch_remove_from_list_job) instead, which removes up to 100 companies from one list in a single request. Rule of thumb: 2+ companies leaving one list → use the batch job; one company leaving one or many lists → use this tool. The list IDs come from the Retrieve Lists and Get List Details endpoints, and must be company lists (e.g. company_123). Credit Note: Removing a company from lists does not consume credits.

remove_company_from_lists

Allows the removal of this contact from one or more lists. Credit Note: Removing a contact from lists does not consume credits. :::info Requires the `contacts:write` OAuth2 scope. :::

remove_contact_from_lists

Retrieve all buyer personas defined in the account. Each buyer persona is a saved set of contact-level filter criteria (department, job title, location, seniority) used to identify target contacts. Credit Note: Retrieving buyer persona definitions does not consume credits. :::info Requires the `buyer_personas:read` OAuth2 scope. :::

get_buyer_personas

Retrieve statistics for a specific campaign over a defined time period. Use frequency, start_period, and end_period to control how the campaign performance data is grouped and returned. :::info Requires the `campaigns:read` OAuth2 scope. ::: Pagination: use `page[num]` to page through results, starting at 1. Increment by 1 for each subsequent page. Stop when `page[num]` exceeds `meta.pagination.page_count`. `page[size]` controls how many items are returned per page (default: 20, max: 100).

get_campaign_stats

Retrieve the list of all campaigns available in the account. Use pagination to control the number of campaigns returned, and include related campaign data, campaign settings, list, or custom feed information when needed. :::info Requires the `campaigns:read` OAuth2 scope. ::: Pagination: use `page[num]` to page through results, starting at 1. Increment by 1 for each subsequent page. Stop when `page[num]` exceeds `meta.pagination.page_count`. `page[size]` controls how many items are returned per page (default: 20, max: 100).

get_campaigns

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. Fetch one or more companies by their Leadfeeder IDs in a single call. Use this instead of calling get_company multiple times when you have more than one ID. Pass the IDs comma-separated in the `ids` parameter, e.g. "159001425,129011" (up to 100 IDs).

get_companies_by_ids

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. Fetch known IP addresses associated with a given set of companies, enabling identification of web traffic and network activity linked to those organizations based on the provided company IDs. Credit Note: Retrieving IP address data consumes 1 credit per company, unless the company's IP data was already accessed within the last 12 months. :::info Requires the `companies:read` OAuth2 scope. :::

get_company_ips

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. Retrieve a list of contacts based on the provided IDs. Credit Note: Each contact will contain its full deep data and it will consume 1 credit, unless the contact has already been accessed within the last 12 months. :::info Requires the `contacts:read` OAuth2 scope. :::

get_contacts

Retrieve all custom feeds accessible to the current user for the given account. :::info Requires the `web_visits:read` OAuth2 scope. :::

get_web_visits_custom_feeds

Retrieve all custom feed folders accessible to the current user for the given account. :::info Requires the `web_visits:read` OAuth2 scope. :::

get_web_visits_custom_feed_folders

Retrieve the list of all custom field definitions available in the account. The response includes each field's attributes. Credit Note: Retrieving custom field definitions does not consume credits. :::info Requires the `custom_fields:read` OAuth2 scope. ::: Pagination: use `page[num]` to page through results, starting at 1. Increment by 1 for each subsequent page. Stop when `page[num]` exceeds `meta.pagination.page_count`. `page[size]` controls how many items are returned per page (default: 20, max: 100).

get_custom_fields

Retrieve all Ideal Customer Profiles (ICPs) defined in the account. Each ICP is a saved set of company-level filter criteria (employee count, industry, location) used to identify target companies. Credit Note: Retrieving ICP definitions does not consume credits. :::info Requires the `icps:read` OAuth2 scope. :::

get_icps

Retrieve the members of a list. The list is addressed by its `{id}`, a scope-prefixed list identifier (e.g. `company_123` or `contact_456`). There is a single `List` resource: the list's `list_type` determines whether the members are companies or contacts. The response contains bare references (IDs only) in `data`, with `type` following the list's `list_type` (`company` for a company list, `contact` for a contact list). Results are cursor-paginated. To retrieve the full company or contact data for these members, pass the returned IDs to the Retrieve Companies (`GET /v1/companies`) or Retrieve Contacts (`GET /v1/contacts`) endpoints. Credit Note: Retrieving list members does not consume credits. :::info Requires the `lists:read` OAuth2 scope. ::: Pagination: pass `page[cursor]` from `meta.pagination.next_cursor` to fetch the next page. Stop when `next_cursor` is null. `page[size]` controls how many items are returned per page (default: 20, max: 100).

get_list_items

Retrieve all lists available in the account. The response includes each list's attributes and can be filtered through query parameters. Credit Note: Retrieving list definitions does not consume credits. :::info Requires the `lists:read` OAuth2 scope. ::: Pagination: use `page[num]` to page through results, starting at 1. Increment by 1 for each subsequent page. Stop when `page[num]` exceeds `meta.pagination.page_count`. `page[size]` controls how many items are returned per page (default: 20, max: 100).

get_lists