Usage examples for every resource live in the README. This page covers what the README doesn’t: what the SDK does on your behalf and the details worth knowing before you ship.
Install and verify
me() is free, so it is the quickest way to confirm your key works. It returns your credit balance and the capabilities of your plan.
What the SDK handles for you
Good to know
Responses are plain dictionaries
Methods return dictionaries with the API’s own field names, so results pass straight tojson.dumps or pandas.DataFrame. Optional fields can be absent or None; read them with .get().
Method arguments use snake_case, such as page_size. Dictionaries you pass in, such as filter or semantic, use the API’s field names, such as autoFilter.
API key resolution
The API key is read from theCOMPANYENRICH_API_KEY environment variable. If your secrets come from somewhere else, pass the key explicitly:
CompanyEnrichError immediately if no key is found, so a missing key fails at startup and not on the first request.
Retry timing
- Failed requests are retried up to twice by default.
- Backoff starts at about 0.5 seconds, doubles on each attempt, and is capped at 8 seconds.
- On a 429, the SDK waits for the period the API specifies instead of guessing.
- If the API asks for a wait longer than 60 seconds, the SDK raises
RateLimitErrorright away so your process isn’t left hanging. Catch it and reschedule the work. - GET requests, and POST requests that cost nothing, are retried after a 408, a 5xx, a timeout, or a dropped connection.
- POST requests that consume credits or start a job are retried only on a 429. They are not repeated after a 5xx, timeout, or dropped connection, because the first attempt may already have been charged.
max_retriescan be overridden per call, not only on the client. Passoptions={"max_retries": 0}to turn retries off for a single request.
Timeouts and large downloads
timeout is in seconds and defaults to 120. It applies to each network operation, such as connecting or waiting for the next chunk of data, and not to the request as a whole. A large stream() or iter_csv() download is not cut off as long as data keeps arriving. Pass timeout=None to disable it.
For large exports, prefer stream() and iter_csv() over results() and csv(), which load the whole result into memory.
Waiting for bulk jobs
batches.wait_for_completion() checks the batch every 2 seconds and waits indefinitely by default. In production, set a ceiling:
batches.get(id). To stop the job itself, call batches.cancel(id). Results that were already charged stay downloadable.
Pagination and credits
The*_all methods request pages as you consume them. Search credits are charged for every result on a fetched page, even if you stop iterating partway through it. Set page_size close to the number of results you plan to use.
Closing connections
Use either client as a context manager, or callclose(), to release network connections. If you pass your own http_client, the SDK does not close it for you.
Proxies, testing, and tracing
base_urlpoints the client at your own proxy or gateway.http_clientaccepts a customhttpx.Clientorhttpx.AsyncClient. Give it anhttpx.MockTransportto stub the API in unit tests without a mocking library.default_headers(client) andoptions={"headers": ...}(per request) let you attach your own correlation IDs.- Requests identify themselves as
companyenrich-python/<version>. The same version string is exported ascompanyenrich.__version__.
Types stay in sync with the API
Request and response types are generated from the public OpenAPI spec, so the fields your editor and type checker see are the fields the API returns. New API fields arrive in the SDK with the next release.Support
- Bugs and feature requests: GitHub issues
- When reporting a failed request, include the
trace_idfrom the error. It lets us find the exact call in our logs.