Your first company search

Ask a question, retrieve a company list, and inspect the evidence.

You will submit a search, then retrieve the results. You need an API key and an active or trialing subscription. Set up authentication first.

Choose how to connect

If you want to ask an AI assistant questions rather than write code, start with Connect your agent. The tutorial below is for developers and uses Bash with cURL.

The API Reference has a language selector above every request example. All languages call the same endpoints and receive the same JSON; there is no separate Jolts SDK to install.

Example	What you need
cURL	A terminal with cURL; this tutorial’s prompts use Bash
Python	Python and the requests package
JavaScript	A server-side runtime with fetch; never expose your key in browser code
Ruby	Ruby with net/http and uri, used by the generated example
PHP	PHP with the cURL extension enabled
Go	Go and the standard-library packages imported by the example
Java	A Java project with the Unirest HTTP client; the generated snippet belongs inside your application

Replace <token> with your secret at runtime, not in committed source. Replace <idempotency-key> with a unique identifier for intentional new work. Reuse it only when retrying the same operation. Generated snippets demonstrate one request; your application still needs to check the status, parse the response, handle errors, and poll a pending operation as shown below.

Make your first request

1. Set your connection

   Run these commands in Bash. Enter the application origin from your account’s address bar, without a trailing slash, then paste your key at the hidden prompt. The docs site is not the API host.

   read -r -p "Application origin: " API_BASE
   read -r -s -p "API key: " API_KEY
   printf '\n'
   export API_BASE API_KEY
   
2. Find companies

   This example looks for evidence relevant to someone selling charging equipment. Change the query to describe the companies and activity you want to research.

   curl --fail-with-body "$API_BASE/api/companies/search" \
     -H "Authorization: Bearer $API_KEY" \
     -H "Idempotency-Key: first-company-search" \
     -H "Content-Type: application/json" \
     -d '{"query":"Companies seeking charging equipment","filters":{"countries":["CA","US"]},"limit":10,"background":true}'
   

   HTTP 202 means the search was accepted, not completed. Copy usage.id from the response. An identical retry can return 200 if the search has already finished.

3. Read the result

   Enter the returned ID, then retrieve the operation:

   read -r -p "Usage ID: " USAGE_ID
   curl --fail-with-body "$API_BASE/api/usages/$USAGE_ID" \
     -H "Authorization: Bearer $API_KEY"
   

   If the response is still 202, wait a few seconds before polling again. On success, inspect companies, each company’s observations, and their evidence. A completed empty list is valid. If error is present, read its code instead of treating it as an empty result.

What you built

One company search with a reusable operation ID. Polling or retrying identical inputs with the same key does not start another search. A new search or next page needs a new idempotency key.

Filter and paginate

Exclude customers you already know and inspect individual companies.

Read the evidence

Understand facts, possible demand, confidence, and coverage.

Troubleshooting

Response	What to do
401	Check your bearer key. A revoked key cannot be reused.
402	Check that your subscription is active or trialing.
422	Read error.code. Correct invalid inputs; do not retry them unchanged.
429	Read error.retry_at when supplied and check /api/usage. Do not loop on the limit.
planning_unavailable	The search could not be prepared. The same key replays that terminal outcome.
idempotency_conflict	The key belongs to different inputs. Use a new key for new work.

After a terminal failure or expiration, use a new key only when you intend to start another operation. For help, share the usage ID and error code, never your API key.