Preview Save Credits

POST/v2/people/calculate-credits

The free preview of POST /v2/people/save (data: the same items, by id or LinkedIn URL) or of a whole search save (filters + optional exclude_ids / limit), exactly one of the two. Reports credits_needed (1 email credit per person with a stored valid email your workspace does not own yet), credits_available and enough_credits, with the breakdown in emails. Costs no credits and reserves nothing. Uses 1 unit of the search rate limit for filters (none when scoped to people you saved), and 1 per started 500 items for data.

Body parameters

filtersobjectoptional

The People Search filter set, also taken by the whole-search save, enrich and credits preview.

Child attributes

personobjectoptional

Match the person themselves, by id, by name, or by LinkedIn URL. id and name are OR-ed with each other - a person matching either is returned - and the result AND-s with every other filter, so a picked person and a typed name can sit side by side in one request. linkedin_url looks up specific profiles and cannot be combined with the other two.

Child attributes

idobjectoptional

Match by person id.

Field	Type	Description
`include`	string[]	Only these people. Use the `id` values returned by People Search results, People Enrich, or Search Suggestions with `type: "person"`. Max 100 ids.
`exclude`	string[]	Reject these people (same `id` values). Max 100 ids.

nameobjectoptional

Match by name.

Field	Type	Description
`include`	string[]	Names to match. Every word of a term must appear somewhere in the name, in any order, so "Dmytro Shulha" matches "Dmytro Shulha, PhD" and "Helena Calero" matches "Helena Montoya-Calero". Case-insensitive; diacritics are significant ("Jose" does not match "José"). Any single term qualifies. Max 500 items.
`exclude`	string[]	Names to reject, matched the same way. Max 500 items.

linkedin_urlobjectoptional

Look up specific profiles by URL.

Field	Type	Description
`include`	string[]	Look up specific profiles by LinkedIn URL. The URLs pick the people and every other filter narrows them - except `company.name.include`, which here only picks which position is returned as `primary_position`. Cannot be combined with `person.id` or `person.name`. Results keep the order of the URLs (`sort_by` does not apply) and each carries the `matched_url` it was found by. 1-50 urls. Example: `["https://linkedin.com/in/emily-carter-sample"]`

Example

{
  "filters": {
    "person": {
      "name": {
        "include": [
          "Dmytro Shulha"
        ]
      }
    }
  }
}

person_locationobjectoptional

Person location filter. Unified location strings resolved to country / state / city.

Field	Type	Description
`include`	string[]	Match these locations (any of). Unified strings like "United States", "Texas, United States", "San Francisco, California, United States" - or a region like "EMEA", "APAC", "Europe", "Latin America", which expands to its member countries (full list with member countries: GET /v2/enums/regions). Max 100 items, each 2-200 chars. If none of the values resolve to a known location, the request fails with 400.
`exclude`	string[]	Reject these locations (same unified-string format). Max 100 items, each 2-200 chars. Values that do not resolve are skipped.

Example

{
  "filters": {
    "person_location": {
      "include": [
        "California, United States",
        "Austin, Texas, United States"
      ],
      "exclude": [
        "San Francisco, California, United States"
      ]
    }
  }
}

company_keywordsobjectoptional

Free-text keyword match against the person's COMPANY (see Keyword sources). Defaults to the specialties source only - the broader text sources match far more companies and are much likelier to exceed the resolution limit. Use POST /v2/search/suggest with type: "company_keywords" for accepted values. Does NOT affect ordering: this resolves to a company-id filter and contributes no relevance score.

Field	Type	Description
`include`	string[]required	Phrases to search for. 1-20 items, 3-100 chars each. Matched as phrases: a multi-word entry like "email finder" requires those words adjacent and in order within one of the selected source fields, not merely present somewhere in it.
`exclude`	string[]	Phrases that disqualify a company. 0-20 items. Matched as phrases, same as `include`.
`include_all`	boolean	When true, every phrase in `include` must match; otherwise any single match qualifies. default: false.
`sources`	enum[]	Restrict matching to these source fields (see Keyword sources). Omit to use the default source set - see this `company_keywords` filter's own description above for what that is.

Example

{
  "filters": {
    "company_keywords": {
      "include": [
        "email marketing"
      ],
      "sources": [
        "specialties"
      ]
    }
  }
}

person_job_titleobjectoptional

Job title match. Structured include/exclude + match_mode (CONTAINS/EXACT), or a boolean_search expression.

Field	Type	Description
`include`	string[]	Job titles to match. Max 100 items, each 2-100 chars. Combined per match_mode. Known abbreviations also match their canonical spelling and vice versa (e.g. "CEO" matches "Chief Executive Officer"), however you spell them - "VP of Marketing", "VP, Marketing" and "Marketing VP" all match what "VP Marketing" matches. Under CONTAINS, terms match any of the roles a position carries - including the secondary roles of combined titles like "Founder & CEO" and the original title text.
`exclude`	string[]	Job titles to reject. Max 100 items, each 2-100 chars.
`match_mode`	enum	CONTAINS = the title contains every word of the term, in any order; connector words (of, and, the, ...) are ignored, so "Director of Sales Enablement" also matches "Director, Sales Enablement". EXACT = the person's LinkedIn title is exactly the term, so "founder" does not match "Founder & CEO", "Founder of Acme LLC" or "Fondateur" - use CONTAINS for those. Applies to include/exclude; ignored when boolean_search is set. Allowed values: `CONTAINS` `EXACT`
`boolean_search`	string	Boolean / Cartesian title query, e.g. "(CEO OR CTO) AND !Intern". Syntax: bareword=contains; 'single quotes'=contains too, and the way to write a title with a space in it - 'vp marketing' matches exactly what include: ["vp marketing"] matches; "double quotes"=exact; `backticks`=words in order with connectors bridged, so `vp marketing` finds "VP of Marketing" but not "VP Sales and Marketing" or "Marketing VP"; !=exclude, AND/OR, ()=grouping. Max 500 terms, depth 5, each term 2-100 chars. AND and OR cannot be mixed at the same nesting level - use parentheses to group. Mutually exclusive with include/exclude. max length: 20000.

Example

{
  "filters": {
    "person_job_title": {
      "include": [
        "Product Marketing Manager",
        "Growth Marketing Manager"
      ],
      "exclude": [
        "Assistant"
      ],
      "match_mode": "CONTAINS"
    }
  }
}

person_seniorityobjectoptional
Seniority (see Seniorities).
Field Type Description
include enum[] Seniority levels to match (any of). See Seniorities.
exclude enum[] Seniority levels to reject. See Seniorities.
Example
```
{
  "filters": {
    "person_seniority": {
      "include": [
        "Chief Officer",
        "VP",
        "Director"
      ]
    }
  }
}
```

Field	Type	Description
`include`	enum[]	Seniority levels to match (any of). See Seniorities.
`exclude`	enum[]	Seniority levels to reject. See Seniorities.

person_departmentobjectoptional

Department (see Departments).

Field	Type	Description
`include`	enum[]	Departments to match (any of). Accepts a department group ("Sales", "Legal") or a specific sub-department ("Sales Operations", "Founder"). A group matches everyone in it; a sub-department matches only that sub-department. See Departments.
`exclude`	enum[]	Departments to reject. A group rejects everyone in it; a sub-department rejects only that sub-department. See Departments.

Example

{
  "filters": {
    "person_department": {
      "include": [
        "Marketing",
        "Sales"
      ],
      "exclude": [
        "Accounting"
      ]
    }
  }
}

person_months_in_current_roleobjectoptional
Months in the current role (tenure of the active position). Integer months 0-600.
Field Type Description
min integer Minimum whole months (inclusive), 0-600. Optional. min: 0, max: 600.
max integer Maximum whole months (inclusive), 0-600, must be >= min. Optional. min: 0, max: 600.
Example
```
{
  "filters": {
    "person_months_in_current_role": {
      "min": 6,
      "max": 24
    }
  }
}
```
person_months_in_current_companyobjectoptional
Months at the current company (tenure since joining). Integer months 0-600.
Field Type Description
min integer Minimum whole months (inclusive), 0-600. Optional. min: 0, max: 600.
max integer Maximum whole months (inclusive), 0-600, must be >= min. Optional. min: 0, max: 600.
Example
```
{
  "filters": {
    "person_months_in_current_company": {
      "min": 12
    }
  }
}
```

Field	Type	Description
`min`	integer	Minimum whole months (inclusive), 0-600. Optional. min: 0, max: 600.
`max`	integer	Maximum whole months (inclusive), 0-600, must be >= min. Optional. min: 0, max: 600.

Field	Type	Description
`min`	integer	Minimum whole months (inclusive), 0-600. Optional. min: 0, max: 600.
`max`	integer	Maximum whole months (inclusive), 0-600, must be >= min. Optional. min: 0, max: 600.

person_job_changeobjectoptional

Recent job change: current role started within timeframe_months, optionally narrowed by change_type.

Field	Type	Description
`timeframe_months`	integerrequired	Months since the current role started, counted in CALENDAR months the way LinkedIn counts them: a role is "N months" if it spans N calendar months inclusive, so a role begun any time in August is 2 months old on 1 September. `timeframe_months: 1` therefore matches only roles begun in the current month. Any whole number from 1 to 1000. Replaces the former `timeframe_days`, which accepted only 30, 60, 90, 180, 270 or 365. min: 1, max: 1000. Example: `3`
`change_type`	enum	any = any recent role change; new_company = also changed company; promotion = changed role at the same company (approximation, includes lateral moves). Allowed values: `any` `promotion` `new_company`

Example

{
  "filters": {
    "person_job_change": {
      "timeframe_months": 3,
      "change_type": "new_company"
    }
  }
}

companyobjectoptional

Company the person works at - by our company id, by domain, by name, or by LinkedIn numeric linkedin_id.

Child attributes

idobjectoptional

Match by company id (the id returned by Company Search and in People Search results). Composes with every other filter: pair it with person_job_title to narrow a company list down to the roles you want. An exact company.name combines with it as OR (people at any listed id or any listed name); company.domain, company_keywords and a CONTAINS company.name AND with it.

Field	Type	Description
`include`	string[]	Only people who work at one of these companies. Use the `id` values returned by Company Search or in People Search results. Combines with an exact `company.name` as OR (a person at any listed id or any listed name); `company.domain`, `company_keywords` and a CONTAINS `company.name` still narrow it. Max 20000 ids.
`exclude`	string[]	Reject people who work at any of these companies (same `id` values). Max 20000 ids.

domainobjectoptional

Match by company website domain. Resolved to the same company-id constraint as company.id, so the two AND together when both are given.

Field	Type	Description
`include`	string[]	Only people who work at the organization that owns one of these domains, e.g. "stripe.com" - see `match_mode` for which of its company pages count. Scheme, "www." and any path are stripped. Max 100 items.
`exclude`	string[]	Reject people whose company is on one of these domains.
`match_mode`	enum	Which company pages an `include` domain stands for. ORGANIZATION (default) = every company page that belongs to the organization owning the domain: its main page, its regional, brand and subsidiary pages. A small page that only links to the domain - a business hosted on a platform, a same-named company - is left out. PRIMARY = only the one main company page of the domain, leaving out the organization's other pages. LINKEDIN_WEBSITE = only the organization's pages whose own LinkedIn website is on the domain, so the domain is never inferred: "stripe.com", "stripe.com/jobs" and "jobs.stripe.com" all match "stripe.com"; a page that lists another site, or no website, does not. `exclude` is not affected: it always rejects every company on the domain. Allowed values: `ORGANIZATION` `PRIMARY` `LINKEDIN_WEBSITE`

Example

{
  "filters": {
    "company": {
      "domain": {
        "include": [
          "stripe.com"
        ]
      }
    }
  }
}

nameobjectoptional

Match by company name - exact by default, or substring with match_mode: CONTAINS. An exact name combines with company.id as OR (people at any listed name or any listed id); a CONTAINS name ANDs with it. Beside person.linkedin_url, include is only a primary-position hint, not a filter (exclude still filters).

Field	Type	Description
`include`	string[]	Company names to match. Combined per match_mode. With EXACT, a value shaped like a website ("stripe.com", "https://www.stripe.com/about") also matches the company on that domain. Max 500 items.
`exclude`	string[]	Company names to reject. With EXACT, a website-shaped value also rejects the company on that domain.
`match_mode`	enum	EXACT (default) = the whole company name equals the term, case-insensitive. CONTAINS = the name contains the term as a substring ("Haven Health" matches "Haven Health Management") - resolved against the company index, so it is slower and capped; narrow the term if the request is rejected. Allowed values: `EXACT` `CONTAINS`

linkedin_idobjectoptional

Only people who work at these LinkedIn companies, by LinkedIn's numeric company id. Composes with every other filter as an AND, including with company.name (unlike company.id, which ORs with an exact name); from a company URL, enrich the company first (POST /v2/companies/enrich) and filter by the id it returns.

Field	Type	Description
`include`	integer[]	Match these LinkedIn companies. LinkedIn's numeric company id. Company URLs are not accepted here - enrich the company by `linkedin_url` first, then filter by the `id` that comes back. Max 500 items. Example: `[162479]`
`exclude`	integer[]	Reject these LinkedIn companies. LinkedIn's numeric company id. Company URLs are not accepted here - enrich the company by `linkedin_url` first, then filter by the `id` that comes back. Max 500 items.

Example

{
  "filters": {
    "company": {
      "name": {
        "include": [
          "Intercom",
          "Stripe"
        ]
      }
    }
  }
}

company_industryobjectoptional

Industry of the person's company (see Industries).

Field	Type	Description
`include`	string[]	Industries or industry GROUPS to match (any of). A group name matches every industry in that category. See Industries for both. Example: `["Agriculture & Mining","Software Development"]`
`exclude`	string[]	Industries or industry GROUPS to reject. A group name rejects every industry in that category. See Industries for both.

Example

{
  "filters": {
    "company_industry": {
      "include": [
        "Software Development",
        "IT Services & IT Consulting"
      ],
      "exclude": [
        "Staffing & Recruiting"
      ]
    }
  }
}

company_headcount_rangeenum[]optional

Bucketed headcount range of the company (see Employee ranges).

Example

{
  "filters": {
    "company_headcount_range": [
      "51-200",
      "201-500"
    ]
  }
}

company_countryobjectoptional

Country of the person's company, as ISO alpha-2 codes (Countries). Any resolved office country counts by default (headquarters included) - same contract as company_location and as Company Search; see headquarters_only. For city/state-level filtering use company_location. sort_by=company_country always orders by the registered headquarters country, independent of headquarters_only.

Field	Type	Description
`include`	string[]	Match values in this list - any single value qualifies (exact, case-insensitive). Optional - provide include and/or exclude.
`exclude`	string[]	Reject values in this list. 0-500 items.
`headquarters_only`	boolean	When true, match the company headquarters country only. When false (default), any office country we have resolved counts, headquarters included: includes widen (a company with an office there matches) and excludes tighten symmetrically (a company with an office there is rejected). default: false.

Example

{
  "filters": {
    "company_country": {
      "include": [
        "US",
        "CA",
        "GB"
      ],
      "headquarters_only": true
    }
  }
}

company_typeobjectoptional

Legal/ownership type of the person's company (see Company types).

Field	Type	Description
`include`	enum[]	Company types to match (any of). Allowed values: `Privately Held` `Public Company` `Non Profit` `Self Owned` `Self Employed` `Partnership` `Educational` `Government Agency` `Unknown`
`exclude`	enum[]	Company types to reject. Allowed values: `Privately Held` `Public Company` `Non Profit` `Self Owned` `Self Employed` `Partnership` `Educational` `Government Agency` `Unknown`

Example

{
  "filters": {
    "company_type": {
      "include": [
        "Privately Held",
        "Public Company"
      ]
    }
  }
}

company_business_typeobjectoptional
Audience type of the person's company (see Business types). Values: B2B, B2C, Nonprofit, Unknown.
Field Type Description
include enum[] Business types to match (any of).
Allowed values: B2B B2C Nonprofit Unknown
exclude enum[] Business types to reject.
Allowed values: B2B B2C Nonprofit Unknown
Example
```
{
  "filters": {
    "company_business_type": {
      "include": [
        "B2B"
      ]
    }
  }
}
```

Field	Type	Description
`include`	enum[]	Business types to match (any of). Allowed values: `B2B` `B2C` `Nonprofit` `Unknown`
`exclude`	enum[]	Business types to reject. Allowed values: `B2B` `B2C` `Nonprofit` `Unknown`

company_revenue_streamobjectoptional

Revenue model of the person's company (see Revenue streams).

Field	Type	Description
`include`	enum[]	Revenue streams to match (any of). Allowed values: `Professional Services` `Product Sales` `Grants / Donations` `Subscriptions / Recurring` `Project / Contract Work` `Event / Experience Revenue` `Transaction Fees` `Rental / Leasing` `Advertising` `Financial Services` `Licensing / IP` `Unknown`
`exclude`	enum[]	Revenue streams to reject. Allowed values: `Professional Services` `Product Sales` `Grants / Donations` `Subscriptions / Recurring` `Project / Contract Work` `Event / Experience Revenue` `Transaction Fees` `Rental / Leasing` `Advertising` `Financial Services` `Licensing / IP` `Unknown`

Example

{
  "filters": {
    "company_revenue_stream": {
      "include": [
        "Subscriptions / Recurring",
        "Product Sales"
      ]
    }
  }
}

company_foundedobjectoptional
Founded-year range of the person's company. min/max are inclusive; either may be omitted.
Field Type Description
min number Lower bound (inclusive). Optional.
max number Upper bound (inclusive). Must be >= min. Optional.
Example
```
{
  "filters": {
    "company_founded": {
      "min": 2015,
      "max": 2023
    }
  }
}
```
company_headcount_customobjectoptional
Raw headcount range of the person's company. min/max are inclusive; either may be omitted.
Field Type Description
min number Lower bound (inclusive). Optional.
max number Upper bound (inclusive). Must be >= min. Optional.
Example
```
{
  "filters": {
    "company_headcount_custom": {
      "min": 50,
      "max": 1000
    }
  }
}
```

Field	Type	Description
`min`	number	Lower bound (inclusive). Optional.
`max`	number	Upper bound (inclusive). Must be >= min. Optional.

Field	Type	Description
`min`	number	Lower bound (inclusive). Optional.
`max`	number	Upper bound (inclusive). Must be >= min. Optional.

company_naicsobjectoptional

NAICS codes (numeric) of the person's company. Matches if any code on the company is in the list.

Field	Type	Description
`include`	number[]	Match numeric values in this list - any single value qualifies. Optional - provide include and/or exclude.
`exclude`	number[]	Reject numeric values in this list. 0-500 items.

Example

{
  "filters": {
    "company_naics": {
      "include": [
        541511,
        541512
      ]
    }
  }
}

company_locationobjectoptional

Location of the person's company (the matched position's company), as unified location strings - same format as person_location. Any resolved office counts by default; see headquarters_only.

Field	Type	Description
`include`	string[]	Match these locations (any of). Unified strings like "United States", "Texas, United States", "San Francisco, California, United States" - or a region like "EMEA", "APAC", "Europe", "Latin America", which expands to its member countries (full list with member countries: GET /v2/enums/regions). Max 100 items, each 2-200 chars. If none of the values resolve to a known location, the request fails with 400.
`exclude`	string[]	Reject these locations (same unified-string format). Max 100 items, each 2-200 chars. Values that do not resolve are skipped.
`headquarters_only`	boolean	When true, match the company headquarters location only. When false (default), any office location we have resolved counts, headquarters included: includes widen (a company with an office there matches) and excludes tighten symmetrically (a company with an office there is rejected). default: false.

Example

{
  "filters": {
    "company_location": {
      "include": [
        "San Francisco, California, United States"
      ],
      "headquarters_only": true
    }
  }
}

company_technologiesobjectoptional

Web technologies detected on the company website, by id: the value of a POST /v2/search/suggest row with type: technology and kind: technology. Websites are rescanned every 30 days. Matches the company of the matched position. Not available yet: answers 400 until the people index carries company technologies.

Field	Type	Description
`include`	string[]	Technology ids to match. `match_mode: ANY` (default): a company using any of them qualifies; `ALL`: it must use every one. Max 500. Example: `["3421"]`
`exclude`	string[]	Reject companies using any of these technology ids. Max 500.
`match_mode`	enum	How `include` combines: `ANY` (default) - at least one; `ALL` - every one, on the same company. Allowed values: `ANY` `ALL`

Example

{
  "filters": {
    "company_technologies": {
      "include": [
        "3421"
      ]
    }
  }
}

company_technology_categoriesobjectoptional
Technology categories (CMS, Ecommerce, Analytics, ...), by id: the value of a suggest row with kind: category. A category matches a company using any technology in it. Matches the company of the matched position. Not available yet: answers 400 until the people index carries company technologies.
Field Type Description
include string[] Category ids to match (any of). Max 200.
Example: ["1"]
exclude string[] Reject companies using any technology in these category ids. Max 200.
Example
```
{
  "filters": {
    "company_technology_categories": {
      "include": [
        "1"
      ]
    }
  }
}
```

Field	Type	Description
`include`	string[]	Category ids to match (any of). Max 200. Example: `["1"]`
`exclude`	string[]	Reject companies using any technology in these category ids. Max 200.

contact_detailsobjectoptional

Contact data: email/phone availability and status (global), plus your workspace's reveal state.

Child attributes

emailobjectoptional

Email availability/quality (global) + your workspace reveal state.

Field	Type	Description
`status`	enum[]	Contact-level email status (best stored email; valid wins). Match-any: valid (>=1 valid email, or an email your workspace entered for the person), invalid, accept_all, not_found (no stored email and none entered by your workspace). Allowed values: `valid` `invalid` `accept_all` `not_found`
`revealed`	boolean	true = only contacts whose email your workspace already revealed; false = only those NOT revealed. Requires an authenticated workspace.

phoneobjectoptional

Phone availability (global) + your workspace reveal state.

Field	Type	Description
`status`	enum[]	Contact-level phone status from our lookup store. Match-any: found (number on file), not_found (looked up, none), unknown (never looked up). Allowed values: `found` `not_found` `unknown`
`revealed`	boolean	true = only contacts whose phone your workspace already revealed; false = only those NOT revealed. Requires an authenticated workspace.

Example

{
  "filters": {
    "contact_details": {
      "email": {
        "status": [
          "valid",
          "accept_all"
        ],
        "revealed": false
      },
      "phone": {
        "status": [
          "found"
        ]
      }
    }
  }
}

listsobjectoptional
Your workspace CRM list membership: include/exclude list ids, saved any/none, and saved-at range.
Child attributes
- includestring[]optional
  Only contacts your workspace saved into these list ids. Max 100 ids, each 1-64 chars.
- excludestring[]optional
  Hide contacts your workspace saved into these list ids. Max 1000 ids, each 1-64 chars.
- savedenumoptional
  any = only contacts your workspace saved, in a list or not; none = only contacts your workspace has not saved; without_list = only contacts your workspace saved but did not file into any list.
  Allowed values: any none without_list
- saved_atobjectoptional
  Filter by when the contact was saved into a list (workspace-scoped).
  Field Type Description
  from string Saved on/after this date (ISO 8601). Optional.
  to string Saved on/before this date (ISO 8601). Optional.
Example
```
{
  "filters": {
    "person_job_title": {
      "include": [
        "Product Marketing Manager"
      ]
    },
    "lists": {
      "saved": "none"
    }
  }
}
```

Field	Type	Description
`from`	string	Saved on/after this date (ISO 8601). Optional.
`to`	string	Saved on/before this date (ISO 8601). Optional.

duplicatesobjectoptional

Deduplication against your workspace's history: hide people already exported.

Field	Type	Description
`exclude_exported`	boolean	true = hide people your workspace already exported through POST /v2/people/export. Exclude-only: it removes rows and never counts as an include condition. Requires an authenticated workspace.

Example

{
  "filters": {
    "duplicates": {
      "exclude_exported": true
    }
  }
}

max_person_per_companyintegeroptionalmin: 1max: 100
Cap the number of people returned per company across the whole result set (1-100). A person is counted against the company of the position that matched your company filters, or their current/primary position when no company filter is set. Of the colleagues competing for a company slot, one we hold a valid email for is kept, and your sort decides between them (and picks the representative outright when none of them has one). Results stay in your sort order either way. For result sets above 25000 matches the representative is simply whoever leads your sort, and total_count is a rounded PRE-cap estimate (pagination.total_is_estimate=true) - an upper bound, so an export of that selection returns fewer people. At or below it both are exact.
Example
```
{
  "filters": {
    "person_job_title": {
      "include": [
        "Product Marketing Manager"
      ]
    },
    "max_person_per_company": 2
  }
}
```

sort_byenumoptional
Sort key. Omit for the default: followers desc. Sorting applies when the result set is under 500,000 people; larger result sets fall back to the default order.
Allowed values: person_first_name person_last_name person_seniority company_employee_count company_name company_industry person_country company_founded person_email_available person_job_title company_country company_type company_business_type company_revenue_stream person_saved_at
sort_directionenumoptional
Sort direction. Per-key defaults apply; ignored when sort_by is omitted.
Allowed values: asc desc
exclude_idsstring[]optional
With filters: profile ids the reader unticked, excluded exactly as the save excludes them.
limitintegeroptionalmin: 1max: 1000000
With filters: how many people the save would take at most (1-25000, defaults to the maximum). The preview of a WHOLE-LIST export - filters holding nothing but lists, naming exactly one list in include or saved: 'any' / saved: 'without_list' alone, with no exclude_ids - may go up to 1000000 and defaults to that; every other request over 25000 is a 400.
list_idsstring[]optional
Accepted so the exact save body can be previewed; lists never change the price, so it is ignored.
dataone of[]optional
People to price (1-25000), the items POST /v2/people/save takes (at most 50 linkedin_url items). The cap is the whole selection, which the client then saves in 500-item requests. Mutually exclusive with filters.

Responses

200 The price now; a zero balance answers enough_credits: false, not 402.
400 Invalid request (VALIDATION_ERROR; payload.code says which kind of mistake), or neither or both of data / filters.
401 Missing, unknown or inactive credentials (UNAUTHORIZED).
429 Over the search rate limit (RATE_LIMIT); wait Retry-After seconds. Sent only where rate limits are enforced.
500 Unexpected server error.

For error handling see Errors. Response objects are described in Person object and Company object.

curl --request POST \
  --url https://api.getprospect.com/v2/people/calculate-credits \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "data": [
    "64f1a2b3c4d5e6f7a8b9c0d1",
    {
      "linkedin_url": "https://linkedin.com/in/emily-carter-sample"
    }
  ]
}
'

Response

{
  "success": true,
  "data": {
    "requested": 2,
    "savable": 1,
    "not_matched": 1,
    "invalid": 0,
    "emails": {
      "to_charge": 1,
      "already_owned": 0,
      "without_email": 0,
      "edited": 0
    },
    "credits_needed": 1,
    "credits_available": 500,
    "enough_credits": true,
    "truncated": false
  },
  "metadata": {
    "timestamp": "2026-10-08T09:30:00.000Z"
  }
}