{ "openapi": "3.0.1", "info": { "title": "BetterContact API", "description": "The official BetterContact API to find new leads and enrich them with verified work emails and mobile phone numbers.", "version": "2.0.0", "contact": { "name": "BetterContact Support", "email": "contact@bettercontact.rocks", "url": "https://doc.bettercontact.rocks" } }, "servers": [ { "url": "https://app.bettercontact.rocks/api/v2" } ], "security": [ { "apiKey": [] } ], "paths": { "/async": { "post": { "summary": "Enrich leads", "operationId": "createEnrichment", "description": "Submit between 1 and 100 leads for waterfall email and phone enrichment.\n\nThis endpoint is asynchronous: it answers immediately with a `id` (the `request_id`) and enriches in the background. Retrieve the results with [`GET /async/{request_id}`](/api-reference/endpoint/get), or provide a `webhook` to have them pushed to you.", "requestBody": { "description": "Data to enrich", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewLeadsEnrichment" } } } }, "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "Enrichment request accepted. Poll `GET /async/{request_id}` or wait for the webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "id": { "type": "string", "example": "your-request-id" }, "message": { "type": "string", "example": "Processing..." } } } } } }, "400": { "description": "Bad request. The `data` attribute is missing or is not an array, or the batch exceeds 100 leads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": "Bad request. Please check documentation" } } } }, "401": { "description": "Unauthorized. The API key is missing, invalid or deactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Payment required. Either the account has no credits left, or the requested feature (`enrich_phone_number`, `verify_catch_all`) is not enabled on the current plan. Read `message` to tell them apart.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "message": "You ran out of credits" } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": "An error occured" } } } } } } }, "/lead_finder/async": { "post": { "summary": "New Lead Finder search", "operationId": "createLeadFinderSearch", "description": "Find new leads from company and people criteria.\n\nThis endpoint is asynchronous: it answers immediately with a `request_id` and searches in the background. Retrieve the results with [`GET /lead_finder/async/{request_id}`](/api-reference/endpoint/lead_finder_get), or provide a `webhook` to have them pushed to you.\n\nSeveral filters only accept exact values from a fixed list. See [Taxonomies](/api-reference/taxonomies).", "requestBody": { "description": "Filters and parameters for lead finding", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadFinderRequest" } } } }, "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "Lead Finder request accepted. Poll `GET /lead_finder/async/{request_id}` or wait for the webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Lead finder request accepted." }, "request_id": { "type": "string", "example": "bc39ffbfc24cf043b748" } } } } } }, "400": { "description": "Bad request. The `filters` object is missing, or every filter is empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": "Filters parameter is invalid. Include and Exclude can not be blank" } } } }, "401": { "description": "Unauthorized. The API key is missing, invalid or deactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Payment required. The account has no credits left.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": "You do not have enough tokens to use Lead Finder API." } } } }, "422": { "description": "Unprocessable. The free Lead Finder search quota is exhausted, the request could not be created, or the search is a single company lookup that belongs on [Enrich a company profile](/api-reference/enrich_profile/company).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "message": "You are out of free lead finder requests. Please upgrade your plan to continue using this feature." } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": "An error occured" } } } } } } }, "/account": { "get": { "summary": "Check your credits balance", "operationId": "getAccount", "description": "Returns the credit balance of the account the API key belongs to.\n\nAuthentication uses the `X-API-Key` header like every other endpoint. The `api_key` query parameter is a legacy alternative kept for backward compatibility; the `email` query parameter is ignored and the email is always resolved from the key.", "parameters": [ { "name": "api_key", "in": "query", "required": false, "schema": { "type": "string" }, "deprecated": true, "description": "Legacy alternative to the `X-API-Key` header. Prefer the header." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Credit balance retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "credits_left": { "type": "integer", "example": 32377, "description": "Credits remaining on the account, across the whole organisation." }, "email": { "type": "string", "example": "your_email@mycompany.com", "description": "Email of the account the API key belongs to." } } } } } }, "401": { "description": "Unauthorized. The API key is missing, invalid or deactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } } }, "/async/{request_id}": { "get": { "summary": "Get enrichment results", "operationId": "getEnrichment", "description": "Retrieve the results of an enrichment request.\n\nAnswers `202` with no `data` while the request is still running, and `200` with `status: \"terminated\"` once it is done. Branch on `status`, never on the HTTP code alone. See [Request statuses](/api-reference/statuses).", "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Request finished. `status` is `terminated` and `data` holds the enriched leads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichmentResult" } } } }, "202": { "description": "Request accepted but not finished yet. `data` and `summary` are absent. Poll again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichmentResult" }, "example": { "id": "fefbc2203558eb3adcea", "status": "processing", "credits_left": 331, "message": "Enrichment is not terminated yet. Please try later" } } } }, "401": { "description": "Unauthorized. The API key is missing, invalid or deactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "406": { "description": "Unknown `request_id`, or the request does not belong to this account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unvalid request_id." } } } } } }, "500": { "description": "Unexpected server error. Safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": "An error occured" } } } } } } }, "/lead_finder/async/{request_id}": { "get": { "summary": "Get Lead Finder search results", "operationId": "getLeadFinderSearch", "description": "Retrieve the results of a Lead Finder search.\n\nAnswers `202` with no `leads` while the search is still running, and `200` with `status: \"terminated\"` once it is done. Branch on `status`, never on the HTTP code alone. See [Request statuses](/api-reference/statuses).", "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Search finished. `status` is `terminated` (`leads` present, possibly empty) or `on_hold` (top up credits to resume).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadFinderResult" } } } }, "202": { "description": "Request accepted but not finished yet. `leads` and `summary` are absent. Poll again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadFinderResult" }, "example": { "id": "bc39ffbfc24cf043b748", "status": "processing", "credits_left": 331, "message": "Lead finder request is not terminated yet. Please try later" } } } }, "401": { "description": "Unauthorized. The API key is missing, invalid or deactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "description": "Unknown `request_id`, or the request does not belong to this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "message": "Lead finder request not found." } } } } } } }, "/company_finder/async": { "post": { "summary": "New Company Finder search", "operationId": "createCompanyFinderSearch", "description": "Find companies from firmographic, funding and hiring criteria.\n\nThis endpoint is asynchronous: it answers immediately with a `request_id` and searches in the background. Retrieve the results with [`GET /company_finder/async/{request_id}`](/api-reference/endpoint/company_finder_get). Company Finder does not send webhooks.\n\nSeveral filters only accept exact values from a fixed list. See [Taxonomies](/api-reference/taxonomies).", "requestBody": { "description": "Filters and pagination for the company search", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyFinderRequest" }, "example": { "limit": 25, "offset": 0, "filters": { "company_industry": { "include": [ "Software Development" ] }, "company_hq_location": { "include": [ "United States" ] }, "company_headcount_min": 51, "company_headcount_max": 500, "is_b2b": true } } } } }, "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "Company Finder request accepted. Poll `GET /company_finder/async/{request_id}`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Company finder request accepted." }, "request_id": { "type": "string", "example": "bc39ffbfc24cf043b748" } } } } } }, "400": { "description": "Bad request. The `filters` object is missing or empty, or every filter in it is blank.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": "Filters parameter is invalid. Include values can not be blank", "message": "Filters parameter is invalid. Include values can not be blank" } } } }, "401": { "description": "Unauthorized. The API key is missing, invalid or deactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Payment required. The account has no credits left.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": "You do not have enough tokens to use Company Finder API.", "message": "You do not have enough tokens to use Company Finder API." } } } }, "422": { "description": "Unprocessable. The free search quota is exhausted, or `limit` is above 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": "You are out of free company finder requests. Please upgrade your plan to continue using this feature.", "message": "You are out of free company finder requests. Please upgrade your plan to continue using this feature." } } } }, "429": { "description": "[Rate limit](/api-reference/api_rate_limits) exceeded. Back off and retry." }, "500": { "description": "Unexpected server error. Safe to retry with backoff, after checking that the first attempt did not create a request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "message": "Company finder request failed." } } } } } } }, "/company_finder/async/{request_id}": { "get": { "summary": "Get Company Finder search results", "operationId": "getCompanyFinderSearch", "description": "Retrieve the results of a Company Finder search.\n\nAnswers `202` with no `companies` while the search is still running, and `200` once it is done. Branch on `status`, never on the HTTP code alone. See [Request statuses](/api-reference/statuses).", "parameters": [ { "name": "request_id", "in": "path", "required": true, "description": "The `request_id` returned by `POST /company_finder/async`.", "schema": { "type": "string" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Search finished. `status` is `terminated` (`companies` and `summary` present, `companies` possibly empty) or `on_hold` (not enough credits for a single company).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyFinderResult" } } } }, "202": { "description": "Request accepted but not finished yet. `companies` and `summary` are absent. Poll again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyFinderResult" }, "example": { "id": "bc39ffbfc24cf043b748", "status": "processing", "credits_left": "999.0", "credits_consumed": "0.0" } } } }, "401": { "description": "Unauthorized. The API key is missing, invalid or deactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "description": "Unknown `request_id`, or the request belongs to another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "message": "Company finder request not found." } } } } } } }, "/enrich_profile/company": { "post": { "summary": "Enrich a company profile", "operationId": "enrichCompany", "description": "Look up a single company by domain, LinkedIn URL, or both. Unlike the other endpoints this one is **synchronous**: the profile comes back in the same response, there is no `request_id` to poll.\n\n**This endpoint does not consume credits.**\n\nAuthentication accepts either the `X-API-Key` header like every other endpoint, or an `api_key` attribute in the request body.", "requestBody": { "description": "Company to look up", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichCompanyRequest" }, "examples": { "byDomain": { "summary": "By domain", "value": { "company_domain": "microsoft.com" } }, "byLinkedin": { "summary": "By LinkedIn URL", "value": { "company_linkedin_url": "https://www.linkedin.com/company/microsoft" } }, "keyInBody": { "summary": "With the key in the body", "value": { "api_key": "YOUR_API_KEY", "company_domain": "microsoft.com" } } } } } }, "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Company found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CompanyProfile" } } } } } }, "401": { "description": "Unauthorized. The API key is missing, invalid or deactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "description": "No company matched the identifier you sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": "Company was not found." } } } }, "422": { "description": "Neither `company_domain` nor `company_linkedin_url` was provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": "company_domain or company_linkedin_url is required." } } } }, "500": { "description": "Unexpected error on our side, or an upstream failure. Safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": "Something bad happened" } } } } } } }, "/enrich_profile/lead": { "post": { "summary": "Enrich a lead profile", "operationId": "enrichLead", "description": "Look up a single person and get their profile plus their current company. This endpoint is **synchronous**: the profile comes back in the same response, there is no `request_id` to poll.\n\n**Cost: 0.1 credit per profile found.** Nothing is charged when no profile matches.\n\nIt returns profile data only. It does **not** return an email address or a phone number: for that, use [Enrich leads](/api-reference/endpoint/create).\n\nAuthentication accepts either the `X-API-Key` header like every other endpoint, or an `api_key` attribute in the request body.", "requestBody": { "description": "Lead to look up", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichLeadRequest" }, "examples": { "byLinkedin": { "summary": "By LinkedIn URL (recommended)", "value": { "linkedin_url": "https://www.linkedin.com/in/veronick-martinuzzi-a4533373" } }, "byNameAndDomain": { "summary": "By name and company domain", "value": { "first_name": "Veronick", "last_name": "Martinuzzi", "company_domain": "hondaresearch.com" } } } } } }, "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Profile found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/LeadProfile" } } } } } }, "400": { "description": "No request body was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": "Data parameter is required." } } } }, "401": { "description": "Unauthorized. The API key is missing, invalid or deactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "402": { "description": "Not enough credits to run the lookup.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": "You do not have enough credits to perform a profile search." } } } }, "404": { "description": "No profile matched. Nothing is charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": "Profile was not found." } } } }, "422": { "description": "Neither `linkedin_url` nor the `first_name` + `last_name` + `company_domain` combination was provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": "Linkedin url OR First_name, last_name, company and company domain is missing" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "NewLeadsEnrichment": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 100, "description": "Leads to enrich. Between 1 and 100 per call. Sending more than 100 is rejected with `400`.", "items": { "type": "object", "required": [ "first_name", "last_name" ], "properties": { "first_name": { "type": "string", "description": "First name of the contact.", "example": "Elon" }, "last_name": { "type": "string", "description": "Last name of the contact.", "example": "Musk" }, "company": { "type": "string", "description": "Company name. Provide either `company` or `company_domain`. `company_domain` gives better results.", "example": "Tesla" }, "company_domain": { "type": "string", "description": "Company domain. Provide either `company` or `company_domain`.", "example": "tesla.com" }, "linkedin_url": { "type": "string", "description": "Public LinkedIn profile URL. Strongly recommended when `enrich_phone_number` is `true`, and required for `enrich_profile`.", "example": "https://www.linkedin.com/in/elonmusk" }, "custom_fields": { "type": "object", "description": "Any data you want echoed back in the response, such as a CRM record id. Keys are free-form; `uuid` and `list_name` below are only an example.\n\nSent as an object, returned as an array of `{ name, value, position }` entries.", "properties": { "uuid": { "type": "string" }, "list_name": { "type": "string" } }, "example": { "uuid": "crm-8821", "list_name": "Q3 outbound" } } } } }, "enrich_email_address": { "type": "boolean", "default": true, "description": "Enrich the work email address. When `enrich_email_address`, `enrich_phone_number` and `enrich_profile` are all omitted or `false`, email enrichment is applied by default." }, "enrich_phone_number": { "type": "boolean", "default": false, "description": "Enrich the mobile phone number. Requires the phone add-on on your plan, otherwise the call is rejected with `402`. Provide `linkedin_url` for best results." }, "enrich_profile": { "type": "boolean", "default": false, "description": "Enrich the full LinkedIn profile of the contact (headline, seniority, location, current company). Requires `linkedin_url`." }, "verify_catch_all": { "type": "boolean", "default": false, "description": "Run the extra catch-all verification layer. When enabled, `contact_email_address_status` returns `catch_all_safe` / `catch_all_not_safe` instead of `catch_all`. Requires the catch-all add-on on your plan, otherwise the call is rejected with `402`." }, "webhook": { "type": "string", "format": "uri", "example": "https://example.com/bettercontact/results", "description": "URL that receives the full result payload as soon as the whole batch is done. Recommended over polling. See [Webhooks](/api-reference/webhooks)." }, "push_contact_individually": { "type": "boolean", "default": false, "description": "When `true`, each lead is pushed to `contact_webhook` as soon as it is enriched, instead of waiting for the whole batch. Useful for batches of 100." }, "contact_webhook": { "type": "string", "format": "uri", "description": "URL that receives one payload per lead. Only used when `push_contact_individually` is `true`." }, "process_flow": { "type": "string", "description": "Identifier of the process flow to use for this enrichment. Only for accounts subscribed to the process flow add-on." }, "timeout_seconds": { "type": "integer", "minimum": 1, "example": 240, "description": "Maximum time the waterfall is allowed to run before the request is terminated with whatever has been found. Defaults to the timeout configured on your account." } } }, "LeadFinderRequest": { "type": "object", "required": [ "filters" ], "properties": { "filters": { "$ref": "#/components/schemas/LeadFinderFilters" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "example": 100, "description": "Number of leads to return for this request, between 1 and 200. Use it together with `offset` to paginate. Mutually exclusive with `max_leads`: when `limit` is set, `max_leads` is ignored." }, "offset": { "type": "integer", "minimum": 0, "default": 0, "example": 100, "description": "Zero-based number of leads to skip before returning matches. Only taken into account when `limit` is set.\n\nTo walk through results, keep `limit` constant and increase `offset` by `limit` on each call: `0`, then `100`, then `200`, and so on. The total number of matching leads is returned as `summary.leads_found`." }, "max_leads": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100, "example": 50, "description": "Number of leads to return when you do not paginate. Between 1 and 200, defaults to 100. Ignored when `limit` is set." }, "webhook": { "type": "string", "nullable": true, "format": "uri", "example": "https://example.com/bettercontact/leads", "description": "URL that receives the results as soon as the search is done, removing the need to poll. See [Webhooks](/api-reference/webhooks)." }, "enrich_email_address": { "type": "boolean", "default": false, "description": "When `true`, every lead found is also run through the waterfall email enrichment before the results are returned. This consumes enrichment credits on top of the search, and the request stays in `processing` until enrichment is done." }, "enrich_phone_number": { "type": "boolean", "default": false, "description": "When `true`, every lead found is also run through the waterfall mobile phone enrichment before the results are returned. This consumes enrichment credits on top of the search. Requires the phone add-on on your plan." } } }, "LeadFinderFilters": { "type": "object", "description": "At least one filter value must be provided, otherwise the request is rejected with `400`.", "properties": { "company": { "$ref": "#/components/schemas/CompanyDomainFilter" }, "company_linkedin_url": { "$ref": "#/components/schemas/CompanyLinkedinUrlFilter" }, "company_industry": { "$ref": "#/components/schemas/CompanyIndustryFilter" }, "company_hq_location": { "$ref": "#/components/schemas/CompanyHqLocationFilter" }, "company_technologies": { "$ref": "#/components/schemas/CompanyTechnologiesFilter" }, "company_keywords": { "$ref": "#/components/schemas/CompanyKeywordsFilter" }, "company_description": { "$ref": "#/components/schemas/CompanyDescriptionFilter" }, "company_headcount_min": { "type": "integer", "example": 51, "description": "Minimum employee count. Converted server-side into the overlapping company size ranges listed in [Taxonomies - Company size ranges](/api-reference/taxonomies#company-size-ranges)." }, "company_headcount_max": { "type": "integer", "example": 1000, "description": "Maximum employee count. Converted server-side into the overlapping company size ranges listed in [Taxonomies - Company size ranges](/api-reference/taxonomies#company-size-ranges)." }, "revenue_ranges": { "$ref": "#/components/schemas/RevenueRangesFilter" }, "last_funding_round_names": { "$ref": "#/components/schemas/FundingRoundNamesFilter" }, "last_funding_date_range": { "allOf": [ { "$ref": "#/components/schemas/RangeFilter" } ], "description": "Date of the last funding round, as `YYYY-MM-DD` strings.", "example": { "gte": "2024-01-01", "lte": "2025-12-31" } }, "last_amount_raised_usd": { "allOf": [ { "$ref": "#/components/schemas/RangeFilter" } ], "description": "Amount raised in the last round, in USD.", "example": { "gte": 1000000 } }, "total_amount_raised_usd": { "allOf": [ { "$ref": "#/components/schemas/RangeFilter" } ], "description": "Total amount raised to date, in USD.", "example": { "gte": 5000000, "lte": 100000000 } }, "is_b2b": { "type": "boolean", "description": "Restrict to companies selling to businesses. `false` is a meaningful value and is sent as-is." }, "is_b2c": { "type": "boolean", "description": "Restrict to companies selling to consumers. `false` is a meaningful value and is sent as-is." }, "is_public": { "type": "boolean", "description": "Restrict to publicly traded companies." }, "job_post_titles": { "allOf": [ { "$ref": "#/components/schemas/JobPostingFilter" } ], "description": "Job titles the company is currently hiring for.", "example": { "include": [ "Account Executive" ] } }, "job_posting_countries": { "allOf": [ { "$ref": "#/components/schemas/JobPostingFilter" } ], "description": "Countries the company is currently hiring in.", "example": { "include": [ "United States" ] } }, "job_posting_locations": { "allOf": [ { "$ref": "#/components/schemas/JobPostingFilter" } ], "description": "Cities or regions the company is currently hiring in.", "example": { "include": [ "Berlin" ] } }, "limit_per_company": { "type": "integer", "minimum": 1, "maximum": 100, "example": 3, "description": "Caps how many leads are returned per company. Useful to spread results across accounts instead of returning a whole org chart. Maximum 100." }, "lead_fullname": { "$ref": "#/components/schemas/FilterObject" }, "lead_linkedin_url": { "$ref": "#/components/schemas/FilterObject" }, "lead_job_title": { "$ref": "#/components/schemas/JobTitleFilter" }, "lead_seniority": { "$ref": "#/components/schemas/SeniorityFilter" }, "lead_department": { "$ref": "#/components/schemas/LeadDepartmentFilter" }, "lead_function": { "$ref": "#/components/schemas/LeadFunctionFilter" }, "lead_skills": { "$ref": "#/components/schemas/FilterObject" }, "lead_location": { "$ref": "#/components/schemas/FilterObject" } } }, "FilterObject": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" }, "description": "Values that must match." }, "exclude": { "type": "array", "items": { "type": "string" }, "description": "Values that must NOT match." } }, "description": "`exclude` is applied by BetterContact after the provider call, so a request made only of `exclude` values matches nothing. Always pair it with at least one `include`." }, "JobTitleFilter": { "allOf": [ { "$ref": "#/components/schemas/FilterObject" }, { "type": "object", "properties": { "exact_match": { "type": "boolean", "default": false, "description": "When `true`, only job titles strictly equal to an `include` value are returned. When `false` (default), titles containing the value also match." } } } ], "description": "Job title filter. This is the only filter whose `exclude` is applied natively by the provider." }, "SeniorityFilter": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" }, "description": "Seniority levels that must match. Must be exact values from the predefined list, see [Taxonomies - Seniority levels](/api-reference/taxonomies#seniority-levels).", "example": [ "cxo", "vp" ] }, "exclude": { "type": "array", "items": { "type": "string" }, "description": "Seniority levels that must NOT match." } }, "description": "`exclude` is applied by BetterContact after the provider call, so a request made only of `exclude` values matches nothing. Always pair it with at least one `include`." }, "CompanyDomainFilter": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" }, "description": "Company domains that must match.", "example": [ "google.com", "microsoft.com" ] }, "exclude": { "type": "array", "items": { "type": "string" }, "description": "Company domains that must NOT match." } }, "description": "Filter on the contact's current company domain. `exclude` is applied by BetterContact after the provider call, so a request made only of `exclude` values matches nothing. Always pair it with at least one `include`." }, "CompanyIndustryFilter": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" }, "description": "Company industries that must match. Must be exact values from the predefined list, see [Taxonomies - Industries](/api-reference/taxonomies#industries).", "example": [ "Computer Software" ] }, "exclude": { "type": "array", "items": { "type": "string" }, "description": "Company industries that must NOT match. Same accepted values as `include`." } }, "description": "`exclude` is applied by BetterContact after the provider call, so a request made only of `exclude` values matches nothing. Always pair it with at least one `include`." }, "LeadDepartmentFilter": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" }, "description": "Lead departments that must match. Must be exact values from the predefined list, see [Taxonomies - Departments](/api-reference/taxonomies#departments).", "example": [ "Sales" ] }, "exclude": { "type": "array", "items": { "type": "string" }, "description": "Lead departments that must NOT match." } }, "description": "`exclude` is applied by BetterContact after the provider call, so a request made only of `exclude` values matches nothing. Always pair it with at least one `include`." }, "LeadFunctionFilter": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" }, "description": "Lead functions that must match. Uses the same accepted values and the same underlying field as `lead_department`, see [Taxonomies - Functions](/api-reference/taxonomies#functions).", "example": [ "Marketing" ] }, "exclude": { "type": "array", "items": { "type": "string" }, "description": "Lead functions that must NOT match." } }, "description": "`lead_function` and `lead_department` resolve to the same provider field. Setting both widens the match rather than narrowing it. `exclude` is applied by BetterContact after the provider call, so a request made only of `exclude` values matches nothing. Always pair it with at least one `include`." }, "EnrichmentResult": { "type": "object", "properties": { "id": { "type": "string", "description": "The `request_id` of this enrichment.", "example": "fefbc2203558eb3adcea" }, "status": { "type": "string", "example": "terminated", "enum": [ "processing", "on_hold", "terminated" ], "description": "See [Request statuses](/api-reference/statuses). Only `terminated` guarantees `data` and `summary` are present." }, "message": { "type": "string", "description": "Human readable hint. Only present while the request is not terminated.", "example": "Enrichment is not terminated yet. Please try later" }, "credits_consumed": { "type": "integer", "description": "Credits spent by this request so far.", "example": 1 }, "credits_left": { "type": "integer", "description": "Credits remaining on the account.", "example": 331 }, "summary": { "type": "object", "description": "Only present once `status` is `terminated`.", "properties": { "total": { "type": "integer", "description": "Number of leads in the request.", "example": 10 }, "valid": { "type": "integer", "description": "Emails verified as `deliverable`.", "example": 6 }, "catch_all": { "type": "integer", "description": "Emails on a catch-all domain. Reported as `catch_all_safe` instead when catch-all verification is enabled.", "example": 2 }, "catch_all_not_safe": { "type": "integer", "description": "Catch-all emails judged unsafe to send to. Only when catch-all verification is enabled.", "example": 1 }, "undeliverable": { "type": "integer", "description": "Emails verified as undeliverable.", "example": 0 }, "not_found": { "type": "integer", "description": "Leads for which no email was found.", "example": 1 }, "found": { "type": "integer", "description": "Phone numbers found. Only present when `enrich_phone_number` was requested.", "example": 4 }, "email_enrichment": { "type": "object", "description": "Only present when `enrich_email_address` was requested.", "properties": { "enriched": { "type": "integer", "description": "", "example": 6 }, "not_enriched": { "type": "integer", "description": "", "example": 4 } } }, "phone_enrichment": { "type": "object", "description": "Only present when `enrich_phone_number` was requested.", "properties": { "enriched": { "type": "integer", "description": "", "example": 4 }, "not_enriched": { "type": "integer", "description": "", "example": 6 } } }, "profile_enrichment": { "type": "object", "description": "Only present when `enrich_profile` was requested.", "properties": { "enriched": { "type": "integer", "description": "", "example": 9 }, "not_enriched": { "type": "integer", "description": "", "example": 1 } } } } }, "data": { "type": "array", "description": "Only present once `status` is `terminated`.", "items": { "$ref": "#/components/schemas/EnrichedContact" } } } }, "LeadFinderResult": { "type": "object", "properties": { "id": { "type": "string", "description": "The `request_id` of this search.", "example": "bc39ffbfc24cf043b748" }, "status": { "type": "string", "example": "terminated", "enum": [ "not_started", "processing", "on_hold", "terminated" ], "description": "See [Request statuses](/api-reference/statuses). A search that matched nothing is reported as `terminated` with an empty `leads` array." }, "message": { "type": "string", "description": "Human readable hint. Only present while the search is not terminated.", "example": "Lead finder request is not terminated yet. Please try later" }, "credits_consumed": { "type": "integer", "description": "Credits spent by this search. Zero unless `enrich_email_address` or `enrich_phone_number` was requested.", "example": 0 }, "credits_left": { "type": "integer", "description": "Credits remaining on the account.", "example": 331 }, "summary": { "type": "object", "description": "Only present once `status` is `terminated`.", "properties": { "leads_found": { "type": "integer", "description": "Total number of leads matching the filters, regardless of `limit`. Use it to size your pagination. Absent when enrichment was requested.", "example": 350 }, "limit": { "type": "integer", "description": "The `limit` used for this page. Only present when paginating.", "example": 100 }, "offset": { "type": "integer", "description": "The `offset` used for this page. Only present when paginating.", "example": 100 }, "total": { "type": "integer", "description": "Number of leads enriched. Only present when enrichment was requested.", "example": 100 }, "valid": { "type": "integer", "description": "Emails verified as `deliverable`. Only present when `enrich_email_address` was requested.", "example": 62 }, "catch_all": { "type": "integer", "description": "Emails on a catch-all domain. Only present when `enrich_email_address` was requested.", "example": 18 }, "catch_all_not_safe": { "type": "integer", "description": "Catch-all emails judged unsafe to send to.", "example": 5 }, "undeliverable": { "type": "integer", "description": "Emails verified as undeliverable.", "example": 3 }, "not_found": { "type": "integer", "description": "Leads for which no email was found.", "example": 17 }, "found": { "type": "integer", "description": "Phone numbers found. Only present when `enrich_phone_number` was requested.", "example": 41 } } }, "leads": { "type": "array", "description": "Only present once `status` is `terminated`. Empty array when nothing matched.", "items": { "$ref": "#/components/schemas/LeadObject" } } } }, "LeadObject": { "type": "object", "description": "One lead returned by the search. Every key below is always present, with `null` when the value is unknown.\n\nFor backward compatibility the response also carries a set of legacy keys that are always `null` (`company_logo`, `company_size`, `contact_avatar`, `company_website`, `company_address_*`, `contact_experience`, `contact_connections`, and others). Ignore them.", "properties": { "contact_id": { "type": "integer", "description": "BetterContact internal identifier for this contact.", "example": 128374651 }, "contact_first_name": { "type": "string", "description": "First name.", "example": "Elon" }, "contact_last_name": { "type": "string", "description": "Last name.", "example": "Musk" }, "contact_full_name": { "type": "string", "description": "First and last name concatenated.", "example": "Elon Musk" }, "contact_job_title": { "type": "string", "description": "Current job title.", "example": "Ceo" }, "contact_seniority": { "type": "string", "description": "Seniority level.", "example": "Cxo" }, "contact_headline": { "type": "string", "description": "LinkedIn headline. Named `contact_linkedin_headline` in the enrichment response." }, "contact_industry": { "type": "string", "description": "Industry of the contact.", "example": "Automotive" }, "contact_gender": { "type": "string", "description": "Inferred gender.", "example": "male" }, "contact_linkedin_profile_url": { "type": "string", "description": "Public LinkedIn profile URL.", "example": "https://www.linkedin.com/in/elonmusk" }, "contact_location_continent": { "type": "string", "description": "Continent.", "example": "North america" }, "contact_location_country": { "type": "string", "description": "Country.", "example": "United states" }, "contact_location_state": { "type": "string", "description": "State or region.", "example": "Texas" }, "contact_location_city": { "type": "string", "description": "City.", "example": "Austin" }, "contact_email_address": { "type": "string", "description": "Work email address. Only filled when `enrich_email_address` was requested.", "example": "elon@tesla.com" }, "contact_email_address_status": { "type": "string", "example": "deliverable", "enum": [ "deliverable", "catch_all", "catch_all_safe", "catch_all_not_safe", "undeliverable", "not_found" ], "description": "Verification verdict. Only filled when `enrich_email_address` was requested." }, "contact_email_address_provider": { "type": "string", "description": "Waterfall vendor that found the email. Vendors under NDA are reported as `Secret Provider`.", "example": "Secret Provider" }, "contact_phone_number": { "type": "string", "description": "Mobile phone number in E.164 format. Only filled when `enrich_phone_number` was requested.", "example": "+14155550101" }, "company_name": { "type": "string", "description": "Company name.", "example": "Tesla" }, "company_domain": { "type": "string", "description": "Company domain.", "example": "tesla.com" }, "company_description": { "type": "string", "description": "Short company description." }, "company_linkedin_url": { "type": "string", "description": "Company LinkedIn page URL. Not provided by the current data source, so it is `null` on most leads." }, "company_industry": { "type": "string", "description": "Company industry.", "example": "Automotive" }, "company_type": { "type": "string", "description": "Company type.", "example": "Public Company" }, "company_keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords associated with the company.", "example": [ "wine industry", "wine" ] }, "company_founded_year": { "type": "integer", "description": "Year the company was founded.", "example": 2003 }, "company_employees_range_start": { "type": "integer", "description": "Lower bound of the headcount range.", "example": 10001 }, "company_employees_range_end": { "type": "integer", "description": "Upper bound of the headcount range.", "example": 50000 }, "company_head_quarters_city": { "type": "string", "description": "Headquarters city. Note the spelling: the enrichment response uses `company_headquarters_city`.", "example": "Austin" }, "company_head_quarters_country": { "type": "string", "description": "Headquarters country. Note the spelling: the enrichment response uses `company_headquarters_country`.", "example": "United states" }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The key you sent." }, "value": { "type": "string", "description": "The value you sent." }, "position": { "type": "integer", "description": "Index of the field in the object you sent." } } }, "description": "Empty for Lead Finder results. Only enrichment requests echo custom fields back.", "example": [] } } }, "UnauthorizedError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "description": "Not returned by the enrichment endpoints." }, "error": { "type": "string", "example": "Your are not authorized. Please check your api_key." } } }, "CompanyHqLocationFilter": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" }, "description": "HQ locations that must match. Accepts country names (e.g. \"United States\"), and also states or cities.", "example": [ "United States", "Germany" ] }, "exclude": { "type": "array", "items": { "type": "string" }, "description": "HQ locations that must NOT match. Same format as `include`." } }, "description": "`exclude` is applied by BetterContact after the provider call, so a request made only of `exclude` values matches nothing. Always pair it with at least one `include`." }, "CompanyTechnologiesFilter": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" }, "description": "Technologies that must match. Must be exact values from the predefined list, see [Taxonomies - Technologies](/api-reference/taxonomies#technologies).", "example": [ "salesforce", "hubspot" ] }, "exclude": { "type": "array", "items": { "type": "string" }, "description": "Technologies that must NOT match. Same accepted values as `include`." } }, "description": "`exclude` is applied by BetterContact after the provider call, so a request made only of `exclude` values matches nothing. Always pair it with at least one `include`." }, "ApiError": { "type": "object", "description": "Generic error envelope. Depending on the endpoint the human readable text is carried by `error` or by `message`, so always read both.", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human readable error message." }, "message": { "type": "string", "description": "Human readable error message." } } }, "EnrichedContact": { "type": "object", "description": "One enriched lead. Every key below is always present, with `null` when the value could not be found.\n\nFor backward compatibility the response also carries a set of legacy keys that are always `null` (`company_logo`, `company_size`, `contact_avatar`, `company_website`, `contact_experience`, `company_address_*`, `contact_additional_phone_number`, and others). Ignore them.", "properties": { "enriched": { "type": "boolean", "example": true, "description": "`true` when the lead was successfully enriched and is not on an opt-out list. Check this before using the row." }, "contact_id": { "type": "integer", "description": "BetterContact internal identifier for this contact.", "example": 128374651 }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The key you sent." }, "value": { "type": "string", "description": "The value you sent." }, "position": { "type": "integer", "description": "Index of the field in the object you sent." } } }, "description": "Your custom fields, echoed back.\n\n**The shape differs from the request**: you send an object, you get back an array of `{ name, value, position }` entries, one per key. Look the field up by `name`, do not index by position.", "example": [ { "name": "uuid", "value": "crm-8821", "position": 0 }, { "name": "list_name", "value": "Q3 outbound", "position": 1 } ] }, "contact_first_name": { "type": "string", "description": "First name of the contact.", "example": "Elon" }, "contact_last_name": { "type": "string", "description": "Last name of the contact.", "example": "Musk" }, "contact_full_name": { "type": "string", "description": "First and last name concatenated.", "example": "Elon Musk" }, "contact_job_title": { "type": "string", "description": "Current job title.", "example": "Ceo of tesla" }, "contact_seniority": { "type": "string", "description": "Seniority level of the contact.", "example": "Cxo" }, "contact_industry": { "type": "string", "description": "Industry of the contact.", "example": "Automotive" }, "contact_linkedin_headline": { "type": "string", "description": "LinkedIn headline of the contact." }, "contact_linkedin_profile_url": { "type": "string", "description": "Public LinkedIn profile URL.", "example": "https://www.linkedin.com/in/elonmusk" }, "contact_location_continent": { "type": "string", "description": "Continent of the contact.", "example": "North america" }, "contact_location_country": { "type": "string", "description": "Country of the contact.", "example": "United states" }, "contact_location_state": { "type": "string", "description": "State or region of the contact.", "example": "Texas" }, "contact_location_city": { "type": "string", "description": "City of the contact.", "example": "Austin" }, "contact_email_address": { "type": "string", "description": "Work email address. `null` when `enrich_email_address` was not requested or nothing was found.", "example": "elon@tesla.com" }, "contact_email_address_status": { "type": "string", "example": "deliverable", "enum": [ "deliverable", "catch_all", "catch_all_safe", "catch_all_not_safe", "undeliverable", "not_found" ], "description": "Verification verdict. `deliverable`, `catch_all` and `catch_all_safe` are safe to send to. `catch_all_not_safe` and `undeliverable` are not. `catch_all_safe` / `catch_all_not_safe` only appear when catch-all verification is enabled on the account." }, "contact_email_address_provider": { "type": "string", "description": "Waterfall vendor that found the email address. Vendors under NDA are reported as `Secret Provider`.", "example": "Secret Provider" }, "email_provider": { "type": "string", "description": "Mailbox host of the email address, not a BetterContact vendor. Do not confuse it with `contact_email_address_provider`.", "example": "google" }, "contact_phone_number": { "type": "string", "description": "Mobile phone number in E.164 format. `null` when `enrich_phone_number` was not requested or nothing was found.", "example": "+14155550101" }, "contact_phone_number_provider": { "type": "string", "description": "Waterfall vendor that found the phone number. Vendors under NDA are reported as `Secret Provider`.", "example": "Secret Provider" }, "company_name": { "type": "string", "description": "Company name.", "example": "Tesla" }, "company_domain": { "type": "string", "description": "Company domain.", "example": "tesla.com" }, "company_description": { "type": "string", "description": "Short company description." }, "company_linkedin_url": { "type": "string", "description": "Company LinkedIn page URL.", "example": "https://www.linkedin.com/company/tesla-motors" }, "company_industry": { "type": "string", "description": "Company industry.", "example": "Automotive" }, "company_type": { "type": "string", "description": "Company type.", "example": "Public Company" }, "company_keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords associated with the company.", "example": [ "wine industry", "wine" ] }, "company_founded_year": { "type": "integer", "description": "Year the company was founded.", "example": 2003 }, "company_employees_range_start": { "type": "integer", "description": "Lower bound of the headcount range.", "example": 10001 }, "company_employees_range_end": { "type": "integer", "description": "Upper bound of the headcount range.", "example": 50000 }, "company_headquarters_city": { "type": "string", "description": "Headquarters city.", "example": "Austin" }, "company_headquarters_country": { "type": "string", "description": "Headquarters country.", "example": "United states" } } }, "RangeFilter": { "type": "object", "description": "Inclusive range. Provide `gte`, `lte` or both.", "properties": { "gte": { "description": "Greater than or equal to." }, "lte": { "description": "Lower than or equal to." } } }, "CompanyLinkedinUrlFilter": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" }, "description": "Company LinkedIn page URLs that must match. Normalised server-side, so both the full URL and the slug are accepted.", "example": [ "https://www.linkedin.com/company/tesla-motors" ] }, "exclude": { "type": "array", "items": { "type": "string" }, "description": "Company LinkedIn page URLs that must NOT match." } }, "description": "`exclude` is applied by BetterContact after the provider call, so a request made only of `exclude` values matches nothing. Always pair it with at least one `include`." }, "CompanyKeywordsFilter": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" }, "description": "Free-text keywords searched across the company profile.", "example": [ "fleet management" ] }, "exclude": { "type": "array", "items": { "type": "string" }, "description": "Keywords that must NOT appear." } }, "description": "Free text, no taxonomy. `company_keywords` and `company_description` are searched against the same underlying field, so combining both widens the match rather than narrowing it. `exclude` is applied by BetterContact after the provider call, so a request made only of `exclude` values matches nothing. Always pair it with at least one `include`." }, "CompanyDescriptionFilter": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" }, "description": "Free-text phrases searched in the company description.", "example": [ "B2B SaaS" ] }, "exclude": { "type": "array", "items": { "type": "string" }, "description": "Phrases that must NOT appear in the company description." } }, "description": "Searched against the same underlying field as `company_keywords`. `exclude` is applied by BetterContact after the provider call, so a request made only of `exclude` values matches nothing. Always pair it with at least one `include`." }, "RevenueRangesFilter": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" }, "description": "Revenue brackets that must match. Must be exact values from the predefined list, see [Taxonomies - Revenue ranges](/api-reference/taxonomies#revenue-ranges).", "example": [ "$20M-$100M", "$100M-$500M" ] }, "exclude": { "type": "array", "items": { "type": "string" }, "description": "Revenue brackets that must NOT match." } }, "description": "`exclude` is applied by BetterContact after the provider call, so a request made only of `exclude` values matches nothing. Always pair it with at least one `include`." }, "FundingRoundNamesFilter": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" }, "description": "Last funding round names that must match. Must be exact values from the predefined list, see [Taxonomies - Funding round names](/api-reference/taxonomies#funding-round-names).", "example": [ "Series A", "Series B" ] }, "exclude": { "type": "array", "items": { "type": "string" }, "description": "Last funding round names that must NOT match." } }, "description": "`exclude` is applied by BetterContact after the provider call, so a request made only of `exclude` values matches nothing. Always pair it with at least one `include`." }, "JobPostingFilter": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" }, "description": "Values that must match on the company's active job postings." }, "exclude": { "type": "array", "items": { "type": "string" }, "description": "Values that must NOT match on the company's active job postings." } }, "description": "Signals based on the company's currently open roles. `exclude` is applied by BetterContact after the provider call, so a request made only of `exclude` values matches nothing. Always pair it with at least one `include`." }, "EnrichCompanyRequest": { "type": "object", "description": "At least one of `company_domain` or `company_linkedin_url` is required. You can send both.", "properties": { "company_domain": { "type": "string", "description": "Company website or domain.", "example": "microsoft.com" }, "company_linkedin_url": { "type": "string", "description": "Company LinkedIn page URL.", "example": "https://www.linkedin.com/company/microsoft" }, "api_key": { "type": "string", "description": "Your API key. Only needed if you do not send the `X-API-Key` header." } } }, "CompanyProfile": { "type": "object", "description": "The company profile. Fields below carry data; every other `company_*` key from the Lead Finder payload is still present and always `null`, kept for payload compatibility. Landbase-only attributes such as `revenue`, `is_b2b` and `technologies_used` are not returned here.", "properties": { "company_id": { "type": "integer", "description": "BetterContact internal company identifier.", "example": 107993854 }, "company_name": { "type": "string", "description": "Company name.", "example": "Bodegas Aragonesas S.A." }, "company_domain": { "type": "string", "description": "Company domain.", "example": "bodegasaragonesas.com" }, "company_website": { "type": "string", "description": "Company website. Same value as `company_domain`.", "example": "bodegasaragonesas.com" }, "company_description": { "type": "string", "description": "Company description.", "example": "Bodegas Aragonesas S.A. is a winery..." }, "company_linkedin_url": { "type": "string", "description": "Company LinkedIn page URL.", "example": "https://www.linkedin.com/company/bodegas-aragonesas-s-a-" }, "company_industry": { "type": "string", "description": "Company industry.", "example": "Beverage Manufacturing" }, "company_type": { "type": "string", "description": "Company type, lowercased with spaces replaced by underscores. `Privately Held` becomes `privately_held`.", "example": "privately_held" }, "company_founded_year": { "type": "integer", "description": "Year the company was founded.", "example": 1984 }, "company_employees_number": { "type": "integer", "description": "Employee count.", "example": 20 }, "company_employees_range_start": { "type": "integer", "description": "Lower bound of the headcount range, parsed from the size range. `11-50` gives `11`.", "example": 11 }, "company_employees_range_end": { "type": "integer", "description": "Upper bound of the headcount range. `null` on open ended ranges: `10000+` sets the start only.", "example": 50, "nullable": true }, "company_headquarters": { "type": "string", "description": "Full headquarters address.", "example": "Carr. de Magallón a la Almunia, S/N; Fuendejalón, Aragón / España 50529, ES" }, "company_head_quarters_city": { "type": "string", "description": "Headquarters city. May be an empty string when the source has no city.", "example": "" }, "company_head_quarters_country": { "type": "string", "description": "Headquarters country.", "example": "Spain" }, "company_address_city": { "type": "string", "description": "City part of the headquarters address.", "example": "" }, "company_address_state": { "type": "string", "description": "State or region part of the headquarters address.", "example": "" }, "company_address_country": { "type": "string", "description": "Country part of the headquarters address.", "example": "Spain" }, "company_address_zipcode": { "type": "string", "description": "Postal code part of the headquarters address.", "example": "" }, "company_keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords associated with the company.", "example": [ "wine industry", "wine" ] } } }, "EnrichLeadRequest": { "type": "object", "description": "Identify the lead in one of two ways:\n\n- **By LinkedIn URL**: send `linkedin_url` alone. This is the most reliable form.\n- **By name and company**: send `first_name`, `last_name` and `company_domain`.\n\n`linkedin_url` takes precedence: when it is present the other attributes are ignored.", "properties": { "linkedin_url": { "type": "string", "description": "Public LinkedIn profile URL of the contact. Sufficient on its own.", "example": "https://www.linkedin.com/in/veronick-martinuzzi-a4533373" }, "first_name": { "type": "string", "description": "First name. Required when you do not send `linkedin_url`.", "example": "Veronick" }, "last_name": { "type": "string", "description": "Last name. Required when you do not send `linkedin_url`.", "example": "Martinuzzi" }, "company_domain": { "type": "string", "description": "Company domain. Required when you do not send `linkedin_url`.", "example": "hondaresearch.com" }, "company": { "type": "string", "description": "Company name. Complements `company_domain`, it cannot replace it.", "example": "Honda R&D Americas" }, "api_key": { "type": "string", "description": "Your API key. Only needed if you do not send the `X-API-Key` header." } } }, "LeadProfile": { "type": "object", "description": "The lead profile. These are all the keys returned: unlike the enrichment and Lead Finder payloads there are no extra always-null legacy keys.", "properties": { "contact_id": { "type": "integer", "description": "BetterContact internal contact identifier.", "example": 98012430, "nullable": true }, "contact_first_name": { "type": "string", "description": "First name.", "example": "Veronick", "nullable": true }, "contact_last_name": { "type": "string", "description": "Last name.", "example": "Martinuzzi", "nullable": true }, "contact_full_name": { "type": "string", "description": "First and last name concatenated.", "example": "Veronick Martinuzzi", "nullable": true }, "contact_job_title": { "type": "string", "description": "Current job title.", "example": "Development solutions sr. principal engineer", "nullable": true }, "contact_seniority": { "type": "string", "description": "Seniority level.", "example": "Senior", "nullable": true }, "contact_industry": { "type": "string", "description": "Industry of the contact.", "example": "Motor vehicle manufacturing", "nullable": true }, "contact_linkedin_headline": { "type": "string", "description": "LinkedIn headline. Often an empty string rather than null.", "example": "", "nullable": true }, "contact_linkedin_profile_url": { "type": "string", "description": "Public LinkedIn profile URL.", "example": "https://www.linkedin.com/in/veronick-martinuzzi-a4533373", "nullable": true }, "contact_location_continent": { "type": "string", "description": "Continent.", "nullable": true }, "contact_location_country": { "type": "string", "description": "Country.", "example": "United states", "nullable": true }, "contact_location_state": { "type": "string", "description": "State or region.", "example": "Ohio", "nullable": true }, "contact_location_city": { "type": "string", "description": "City.", "nullable": true }, "company_name": { "type": "string", "description": "Company name.", "example": "Honda rd americas", "nullable": true }, "company_domain": { "type": "string", "description": "Company domain.", "example": "hondaresearch.com", "nullable": true }, "company_description": { "type": "string", "description": "Company description.", "nullable": true }, "company_linkedin_url": { "type": "string", "description": "Company LinkedIn page URL.", "example": "https://www.linkedin.com/company/honda-r&d", "nullable": true }, "company_industry": { "type": "string", "description": "Company industry.", "example": "Motor vehicle manufacturing", "nullable": true }, "company_type": { "type": "string", "description": "Company type.", "nullable": true }, "company_founded_year": { "type": "integer", "description": "Year the company was founded.", "nullable": true }, "company_employees_range_start": { "type": "integer", "description": "Lower bound of the headcount range.", "example": 10001, "nullable": true }, "company_employees_range_end": { "type": "integer", "description": "Upper bound of the headcount range. `null` on open ended ranges such as `10001+`.", "nullable": true }, "company_headquarters_city": { "type": "string", "description": "Headquarters city. Can carry a full street address rather than a bare city name.", "example": "Ohio center; 21001 state route 739; raymond", "nullable": true }, "company_headquarters_country": { "type": "string", "description": "Headquarters country.", "example": "United states", "nullable": true }, "company_keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords associated with the company.", "example": [ "automotive", "auto development", "design", "research", "products", "honda" ] } } }, "CompanyFinderIncludeFilter": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" }, "description": "Values that must match." } }, "description": "Company Finder list filters only take `include`. There is no `exclude`." }, "CompanyFinderFilters": { "type": "object", "description": "Company criteria. At least one filter must hold a real value. Unknown keys are ignored, and so is `exclude`: a request made only of those is refused with `400`.", "properties": { "company": { "allOf": [ { "$ref": "#/components/schemas/CompanyFinderIncludeFilter" } ], "description": "Company domains, in lowercase: the match is case-sensitive, so `HUBSPOT.COM` finds nothing. A leading `http://`, `https://` or `www.` is stripped, but a path is not: pass `acme.com`, not `https://acme.com/about`.", "example": { "include": [ "acme.com" ] } }, "company_linkedin_url": { "allOf": [ { "$ref": "#/components/schemas/CompanyFinderIncludeFilter" } ], "description": "Company LinkedIn page URLs.", "example": { "include": [ "https://www.linkedin.com/company/acme" ] } }, "company_industry": { "allOf": [ { "$ref": "#/components/schemas/CompanyFinderIncludeFilter" } ], "description": "Industries. Must be exact values from [Taxonomies - Industries](/api-reference/taxonomies#industries).", "example": { "include": [ "Software Development" ] } }, "company_hq_location": { "allOf": [ { "$ref": "#/components/schemas/CompanyFinderIncludeFilter" } ], "description": "Matched against the full headquarters address, so a city, a state or a country all work.", "example": { "include": [ "Austin", "Germany" ] } }, "company_technologies": { "allOf": [ { "$ref": "#/components/schemas/CompanyFinderIncludeFilter" } ], "description": "Technologies the company uses. Must be exact values from [Taxonomies - Technologies](/api-reference/taxonomies#technologies).", "example": { "include": [ "Salesforce" ] } }, "company_keywords": { "allOf": [ { "$ref": "#/components/schemas/CompanyFinderIncludeFilter" } ], "description": "Keywords or phrases matched against the company profile. Matched the same way as `company_description`.", "example": { "include": [ "fintech" ] } }, "company_description": { "allOf": [ { "$ref": "#/components/schemas/CompanyFinderIncludeFilter" } ], "description": "Phrases matched against the company profile. Matched the same way as `company_keywords`.", "example": { "include": [ "payment infrastructure" ] } }, "company_headcount_min": { "type": "integer", "minimum": 0, "description": "Minimum number of employees, inclusive. Mapped onto the size buckets of [Taxonomies - Company size ranges](/api-reference/taxonomies#company-size-ranges): every bucket that overlaps your range is kept, so `60` still returns companies from the `51-200` bucket.", "example": 51 }, "company_headcount_max": { "type": "integer", "minimum": 0, "description": "Maximum number of employees, inclusive. Mapped onto size buckets the same way as `company_headcount_min`.", "example": 500 }, "is_b2b": { "type": "boolean", "description": "`true` keeps companies that sell to businesses. Omit the field when you do not want to filter on it." }, "is_b2c": { "type": "boolean", "description": "`true` keeps companies that sell to consumers. Omit the field when you do not want to filter on it." }, "is_public": { "type": "boolean", "description": "`true` keeps publicly listed companies. Omit the field when you do not want to filter on it." }, "revenue_ranges": { "allOf": [ { "$ref": "#/components/schemas/CompanyFinderIncludeFilter" } ], "description": "Revenue brackets. Must be exact values from [Taxonomies - Revenue ranges](/api-reference/taxonomies#revenue-ranges).", "example": { "include": [ "$20M-$100M" ] } }, "last_funding_round_names": { "allOf": [ { "$ref": "#/components/schemas/CompanyFinderIncludeFilter" } ], "description": "Name of the latest funding round. Must be exact values from [Taxonomies - Funding round names](/api-reference/taxonomies#funding-round-names).", "example": { "include": [ "Series B" ] } }, "last_funding_date_range": { "allOf": [ { "$ref": "#/components/schemas/RangeFilter" } ], "description": "Date of the last funding round, as `YYYY-MM-DD` strings.", "example": { "gte": "2024-01-01", "lte": "2025-12-31" } }, "last_amount_raised_usd": { "allOf": [ { "$ref": "#/components/schemas/RangeFilter" } ], "description": "Amount raised in the last round, in USD, as integers.", "example": { "gte": 1000000 } }, "total_amount_raised_usd": { "allOf": [ { "$ref": "#/components/schemas/RangeFilter" } ], "description": "Total amount raised, in USD, as integers.", "example": { "gte": 5000000, "lte": 50000000 } }, "job_post_titles": { "allOf": [ { "$ref": "#/components/schemas/CompanyFinderIncludeFilter" } ], "description": "Job titles the company is currently hiring for.", "example": { "include": [ "Account Executive" ] } }, "job_posting_countries": { "allOf": [ { "$ref": "#/components/schemas/CompanyFinderIncludeFilter" } ], "description": "Countries the company is currently hiring in.", "example": { "include": [ "United States" ] } }, "job_posting_locations": { "allOf": [ { "$ref": "#/components/schemas/CompanyFinderIncludeFilter" } ], "description": "Cities or regions the company is currently hiring in.", "example": { "include": [ "Berlin" ] } } } }, "CompanyFinderRequest": { "type": "object", "required": [ "filters" ], "properties": { "filters": { "$ref": "#/components/schemas/CompanyFinderFilters" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100, "example": 100, "description": "Number of companies to return for this page, between 1 and 200. Defaults to 100. A value above 200 is refused with `422`; `0`, a negative number or a non-numeric value falls back to the default." }, "offset": { "type": "integer", "minimum": 0, "default": 0, "example": 0, "description": "Zero-based number of matches to skip. A negative value is treated as `0`.\n\nTo walk through results, keep `limit` constant and increase `offset` by `limit` on each call. The total number of matching companies is returned as `summary.companies_found`." } } }, "CompanyFinderCompany": { "type": "object", "description": "One company returned by the search. A field is `null` when the value is unknown.", "properties": { "company_id": { "type": "integer", "description": "BetterContact identifier for this company.", "example": 42 }, "company_name": { "type": "string", "example": "Acme" }, "company_domain": { "type": "string", "example": "acme.com" }, "company_website": { "type": "string", "nullable": true, "example": "acme.com", "description": "Website, usually a bare domain without scheme." }, "company_linkedin_url": { "type": "string", "nullable": true, "example": "https://www.linkedin.com/company/acme" }, "company_crunchbase_url": { "type": "string", "nullable": true, "example": "https://www.crunchbase.com/organization/acme" }, "company_logo_url": { "type": "string", "nullable": true, "example": "https://logo.example/acme.png" }, "company_industry": { "type": "string", "nullable": true, "example": "Software" }, "company_type": { "type": "string", "nullable": true, "example": "Privately Held" }, "company_description": { "type": "string", "nullable": true }, "company_founded_year": { "type": "integer", "nullable": true, "example": 2012 }, "company_keywords": { "type": "array", "nullable": true, "items": { "type": "string" }, "example": [ "saas" ] }, "company_technologies": { "type": "array", "nullable": true, "items": { "type": "string" }, "example": [ "Ruby", "PostgreSQL" ] }, "company_employees_range_start": { "type": "integer", "nullable": true, "description": "Lower bound of the headcount range.", "example": 51 }, "company_employees_range_end": { "type": "integer", "nullable": true, "description": "Upper bound of the headcount range.", "example": 200 }, "company_employees_count": { "type": "integer", "nullable": true, "description": "Exact employee count, when known.", "example": 120 }, "company_employees_by_department": { "type": "object", "nullable": true, "additionalProperties": { "type": "integer" }, "description": "Headcount per department.", "example": { "Engineering": 40, "Sales": 15 } }, "company_size_range": { "type": "string", "nullable": true, "example": "51-200" }, "company_revenue_range": { "type": "string", "nullable": true, "example": "$10M-$50M" }, "company_locations_count": { "type": "integer", "nullable": true, "description": "Number of company locations.", "example": 3 }, "company_last_funding_round_name": { "type": "string", "nullable": true, "example": "Series B" }, "company_last_amount_raised_usd": { "type": "integer", "nullable": true, "example": 25000000 }, "company_total_amount_raised_usd": { "type": "integer", "nullable": true, "example": 40000000 }, "company_last_funding_date": { "type": "string", "nullable": true, "description": "`YYYY-MM-DD`.", "example": "2024-06-01" }, "company_head_quarters_city": { "type": "string", "nullable": true, "example": "Austin" }, "company_head_quarters_state": { "type": "string", "nullable": true, "example": "Texas" }, "company_head_quarters_country": { "type": "string", "nullable": true, "example": "United States" }, "company_head_quarters_address": { "type": "string", "nullable": true }, "company_active_job_postings_count": { "type": "integer", "nullable": true, "description": "Number of open roles, when known.", "example": 8 } } }, "CompanyFinderResult": { "type": "object", "properties": { "id": { "type": "string", "description": "The `request_id` of this search.", "example": "bc39ffbfc24cf043b748" }, "status": { "type": "string", "enum": [ "not_started", "processing", "on_hold", "terminated" ], "example": "terminated", "description": "See [Request statuses](/api-reference/statuses). A search that matched nothing is reported as `terminated` with an empty `companies` array." }, "credits_consumed": { "type": "string", "description": "Credits spent by this search, as a decimal string.", "example": "2.5" }, "credits_left": { "type": "string", "description": "Credits remaining on the account, as a decimal string.", "example": "998.5" }, "summary": { "type": "object", "description": "Only present once `status` is `terminated`.", "properties": { "companies_found": { "type": "integer", "description": "Total number of companies matching the filters, regardless of `limit`. Use it to size your pagination.", "example": 68067 }, "limit": { "type": "integer", "description": "The `limit` used for this page.", "example": 25 }, "offset": { "type": "integer", "description": "The `offset` used for this page.", "example": 0 } } }, "companies": { "type": "array", "description": "Only present once `status` is `terminated`. An empty array when nothing matched.", "items": { "$ref": "#/components/schemas/CompanyFinderCompany" } } } } } } }