This tutorial uses an authorized workspace API key at https://app.vencavo.com. Create an account, verify your email, and select a workspace before creating a key. A successful nonempty search spends one credit.

Prepare a temporary key

  1. Sign in and select your workspace.
  2. As an owner or admin, open Developer access and create a temporary key with directory:read and billing:read. Workspace identification is included.
  3. Set VENACOVA_ORIGIN to https://app.vencavo.com. Set VENACOVA_API_KEY securely outside shell history and source control.

Do not substitute the marketing domain. Send exactly one credential type. Do not send browser cookies with the key.

Identify the workspace

curl --fail-with-body --silent --show-error \
	-H "X-Api-Key: $VENACOVA_API_KEY" \
	"$VENACOVA_ORIGIN/api/v1/workspace"

Check the returned workspace ID, name, and data-connection status. Stop if the workspace differs from your intended workspace.

Search one bounded page

Agree to spend at most one search credit. The following body searches companies in India using the supported structured country filter.

VENACOVA_OPERATION_KEY=$(uuidgen)
curl --fail-with-body --silent --show-error --include \
	-H "X-Api-Key: $VENACOVA_API_KEY" \
	-H 'Content-Type: application/json' \
	-H "Idempotency-Key: $VENACOVA_OPERATION_KEY" \
	--data '{"query":"","limit":10,"filters":[{"field":"companyCountry","include":["IN"],"exclude":[]}]}' \
	"$VENACOVA_ORIGIN/api/v1/directory/companies/search"

A nonempty page costs one credit. An empty page costs zero. Preserve the returned IDs, source.mode, source.release, nextCursor, and usage receipt. No particular company or result count is promised. Fixture results remain samples.

Repeat the exact request

Run the same curl command again with the same operation key, credential, and body. A replay returns the recorded response body and X-Idempotent-Replay: true, without a second debit. The balance in that recorded body is historical.

To inspect the current balance, call /api/v1/billing with the same API key. Free requests and retries still count against request limits.

Inspect a returned company

Set VENACOVA_COMPANY_ID to an ID from your actual search result. URL-encode the ID when constructing the path. Do not use a fictional website domain or a fixture ID from another provider.

curl --fail-with-body --silent --show-error \
	-H "X-Api-Key: $VENACOVA_API_KEY" \
	"$VENACOVA_ORIGIN/api/v1/directory/companies/$VENACOVA_COMPANY_ID"

The free profile contains the available company fields and at most 50 previewed people. Preserve unknowns and source labels. Use the deployment’s /api/docs/reference and /api/openapi.json for complete response and save schemas.

Finish the test

Revoke the temporary key in Developer access. Repeat the workspace request and confirm rejection. Remove the secret from your shell.

unset VENACOVA_API_KEY

For a new page, pass the returned nextCursor as cursor, retain criteria, order, and limit, and generate a new operation key. An uncertain response requires the original key. Read search credits and error recovery before continuing.

People searches also accept { "field": "companyId", "include": ["<company-id>"], "exclude": [] } in filters, with up to 50 exact IDs. Keep the legacy top-level companyId empty and combine the selection with supported people filters. See search criteria for selection, pagination and index-availability rules.