> ## Documentation Index
> Fetch the complete documentation index at: https://doc.bettercontact.rocks/llms.txt
> Use this file to discover all available pages before exploring further.
# Get a Company Finder Search results
> Get companies from a submitted Company Finder search.
**Poll on `status`, not on the HTTP status code.**
While the search is running this endpoint answers `202 Accepted` with a body that has no
`companies` and no `summary`. Once it is done it answers `200 OK` with `status` set to
`terminated` or `on_hold`.
Always branch on `body.status`, never on the HTTP code alone.
See [Request statuses](/api-reference/statuses) for the full lifecycle and a polling recipe.
## Reading the result
| `status` | HTTP | What you get |
| - | - | - |
| `not_started`, `processing` | `202` | `id`, `status`, `credits_left`, `credits_consumed`. Poll again. |
| `terminated` | `200` | `summary` and `companies`. When nothing matched, `companies` is `[]` and `summary.companies_found` is `0`. |
| `on_hold` | `200` | No results. The balance could not cover a single company. |
An `on_hold` Company Finder search does **not** resume after a top up. Top up, then submit the
search again. Nothing was charged for the first one.
Put a timeout on your polling loop. If the search provider fails, the request can stay in
`processing` instead of moving to a final status.
`credits_left` and `credits_consumed` are returned as decimal strings, for example `"998.5"`. Parse
them before doing arithmetic.
## OpenAPI
````yaml GET /company_finder/async/{request_id}
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:
/company_finder/async/{request_id}:
get:
summary: Get Company Finder search results
description: >-
Retrieve the results of a Company Finder search.
Answers `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).
operationId: getCompanyFinderSearch
parameters:
- name: request_id
in: path
required: true
description: The `request_id` returned by `POST /company_finder/async`.
schema:
type: string
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.
security:
- apiKey: []
components:
schemas:
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'
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.
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.
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
securitySchemes:
apiKey:
type: apiKey
in: header
name: X-API-Key
````