--- title: "Reveal people" method: POST path: "/api/v1/people/reveal" tags: ["People"] --- # Reveal people `POST /api/v1/people/reveal` ## Request - Base URL: `https://app.argorant.com` - URL: `https://app.argorant.com/api/v1/people/reveal` - Auth: HTTP bearer Full details for people, with name, title, company, work email, profile URL and place. Send `record_ids` from a search (up to 25), or the same filters as search to take the next people who match. Every email is checked right before you get it; only people whose email passes are returned and charged. A person you revealed before is free to reveal again. Ask the user before you spend: show the count and the price first. A key can reveal 100 people a day. For bigger numbers use a saved list and an export, or add the list to a campaign. | Cost | What it does | Key scopes | | --- | --- | --- | | 1 credit per contact whose email passes the check; contacts that fail are left out and cost nothing | Spends credits | `argorant:unlock_contacts` | ## Headers - `Idempotency-Key` string - `X-Request-Id` string ## Request body - object - `record_ids` string[]: Up to 25 record ids from a search. Leave out to reveal by filters. - `q` string: Plain text across name, title, company and description. A request like "software companies selling to restaurants" is understood as the vendors, not the restaurants. - `title` string: Job title. Knows abbreviations (CFO matches Chief Financial Officer). Comma means or. - `exclude_title` string: Leave out people with these titles. Comma means or. - `seniority` 'Owner' | 'Founder' | 'Partner' | 'C-Level' | 'VP' | 'Director' | 'Manager' | 'Senior' | 'Entry' | 'Intern': Comma-separated seniority levels. - `departments` 'Sales' | 'Marketing' | 'Engineering' | 'Product' | 'Finance' | 'Human Resources' | 'Operations' | 'Legal' | 'Customer Success' | 'IT' | 'Design' | 'Data' | 'Research' | 'Executive': Comma-separated departments. - `industries` string: Pipe-separated industries from GET /api/v1/lookups/industries. - `industry` string: One industry in plain words; industries is more exact. - `keywords` string: Comma-separated words that describe what the company does, such as fintech or freight forwarding. They match the company's name, tags, industry and description. They do not match a person's own skills unless keyword_scope is people or any. The widest filter for niches without their own industry. - `technologies` string: Pipe-separated technologies the company uses, from GET /api/v1/lookups/technologies. - `employee_range` '1-10' | '11-50' | '51-200' | '201-500' | '501-1000' | '1001-5000' | '5001-10000' | '10000+' | 'unknown': Comma-separated company sizes. - `company_name` string: Company name, matched as written (Deutsche Bank finds Deutsche Bank AG). Several companies: join the names with |, for example Stripe|Notion. - `company_domain` string: Company website domains. Comma means or. - `country` string: Comma-separated countries or regions (Europe, DACH, Nordics, APAC, LATAM). Names from GET /api/v1/lookups/countries. - `state` string: States or provinces, by name or code. Comma means or. - `city` string: Cities. Comma means or. - `sells_to` string: Who the company sells to, for example restaurants or dentists. - `company_category` 'software' | 'payments' | 'fintech' | 'formation' | 'association' | 'marketplace' | 'investors': What the company itself is, used with sells_to. - `has_phone` boolean: Only people with a phone number on record. - `has_linkedin` boolean: Only people with a profile URL. - `exclude_keywords` string: Leave out people that keywords would find for these words. Same matching and the same keyword_scope as keywords. Comma means or. - `keyword_scope` 'company' | 'people' | 'any': company (default): only what the company does, that is its name, tags, industry and description. people: only the person's own skills and profile; use it when the user wants people who have a skill themselves, such as people who know Python. any: both, plus job titles. - `title_match` 'words' | 'exact' | 'contains': words (default): every word must appear as a whole word, so Data does not match Database. exact: the whole job title must be one of the values, ignoring case, so CEO does not match Founder & CEO. contains: the text may appear anywhere, also inside a word; slower, for special cases. - `exclude_title_match` 'words' | 'exact' | 'contains': Like title_match, for exclude_title only. When it is not set, title_match is used. - `exclude_seniority` 'Owner' | 'Founder' | 'Partner' | 'C-Level' | 'VP' | 'Director' | 'Manager' | 'Senior' | 'Entry' | 'Intern': Leave out these seniority levels. Comma means or. - `exclude_departments` 'Sales' | 'Marketing' | 'Engineering' | 'Product' | 'Finance' | 'Human Resources' | 'Operations' | 'Legal' | 'Customer Success' | 'IT' | 'Design' | 'Data' | 'Research' | 'Executive': Leave out these departments. Comma means or. - `exclude_industries` string: Leave out these industries (pipe-separated, like industries). - `exclude_industry` string: Leave out industries in plain words, like industry. Comma means or. - `exclude_company_domain` string: Leave out people at these company website domains. Comma means or. - `exclude_country` string: Leave out these countries or regions (Europe, DACH, Nordics, APAC, LATAM). Comma means or. - `exclude_state` string: Leave out these states or provinces, by name or code. Comma means or. - `exclude_city` string: Leave out these cities. Comma means or. - `employees_min` string: Smallest number of employees, such as 50 and 500. A company counts when its size range overlaps yours. Accepts 100 or 1k. - `employees_max` string: Largest number of employees (same overlap rule). - `revenue_band` '0-1m' | '1m-10m' | '10m-50m' | '50m-100m' | '100m-250m' | '250m-500m' | '500m-1b' | '1b-10b' | '10b+': Yearly company revenue in US dollars, as bands. A comma means any of them. - `revenue_min` string: Smallest yearly revenue in US dollars; a company counts when its revenue range overlaps yours. Accepts 250k, 1.5M or 2B. - `revenue_max` string: Largest yearly revenue in US dollars (same overlap rule). - `limit` integer: How many people when revealing by filters, 1 to 25 per call (default 10). - `grade` 'valid' | 'valid_plus_catchall': valid: only confirmed addresses. valid_plus_catchall: also addresses at domains that accept every email. Default: both. ## Response `200` OK - Person: A revealed contact with a checked work email. - `record_id` string: Stable Argorant id of this person. - `first_name` string, nullable: First name. - `last_name` string, nullable: Last name. - `full_name` string, nullable: Full name. - `title` string, nullable: Job title. - `seniority` string, nullable: Seniority. - `departments` string[]: Departments. - `company` string, nullable: Company name as recorded. - `company_normalized` string, nullable: The company name people say. - `company_domain` string, nullable: Company website domain. - `email` string, email, nullable: Work email. Present only when it passed the check. - `email_status` 'valid' | 'catch_all' | 'risky' | 'null', nullable: Result of the check at reveal time: valid, or catch_all for a domain that accepts every address. - `phone` string, nullable: Phone number, only when this account already unlocked it. Ask for numbers with POST /api/v1/people/phones. - `linkedin_url` string, uri, nullable: Profile URL. - `city` string, nullable: City. - `state` string, nullable: State or region. - `country` string, nullable: Country. - `industry` string, nullable: Main industry. - `industries` string[]: All industry labels. ## Other responses - `401`: 401 Unauthorized. `unauthorized` when the API key is missing, wrong or revoked. - `402`: 402 Payment required. `insufficient_credits` when the balance does not cover the people asked for. - `403`: 403 Forbidden. `scope_missing` when the key lacks argorant:unlock_contacts; `permission_missing` when your workspace role may not reveal contacts. - `409`: 409 Conflict. `idempotency_conflict` when the Idempotency-Key was used with another body. - `422`: 422 Validation error. `validation_error` when a field has the wrong type or is missing. - `429`: 429 Too many requests. `daily_limit_reached` when during the trial, 100 revealed people a day per key are used up (plans have no daily limit; credits bound reveals); `rate_limited` when too many requests this minute. --- [API](https://skmtc.dev/argorant/apis/argorant-api.md) · [All operations](https://skmtc.dev/argorant/apis/argorant-api/llms.txt) · [OpenAPI document](https://skmtc.dev/argorant/apis/argorant-api/revisions/4bc28c0085b6?raw)