Getting Started

Authentication

Copy page

All B2BEnrich API endpoints are authenticated using an API key.

API key authentication

The OpenAPI spec defines a single auth scheme:

• Type: API key
• Location: HTTP header
• Header name: X-Api-Key

The spec also sets this scheme as global security, which means every operation requires X-Api-Key unless explicitly overridden.

Base URLs

The API advertises these server URLs:

• Production: https://a.b2benrich.com
• Local development: http://localhost:8084

Send the API key

Include your key on every request:

Code
 
curl -sS \
	-H "X-Api-Key: $b2benrich_API_KEY" \
	https://a.b2benrich.com/api/organizations/get-id

If you prefer, export it once:

Code
 
export b2benrich_API_KEY="your_api_key_here"

Validate your key

The following endpoints are useful for verifying your API key and organization context:

Get organization id

Returns the organization_id associated with the provided API key.

Code
 
curl -sS \
	-H "X-Api-Key: $b2benrich_API_KEY" \
	https://a.b2benrich.com/api/organizations/get-id

Get credit balance

Returns the current credit balance for the API key's organization.

Code
 
curl -sS \
	-H "X-Api-Key: $b2benrich_API_KEY" \
	https://a.b2benrich.com/api/organizations/credit-balance

Example authenticated request

Most API operations are JSON POST requests and require you to include your organization_id in the body.

Example: create a contact

Code
 
curl -sS \
	-H "X-Api-Key: $b2benrich_API_KEY" \
	-H "Content-Type: application/json" \
	-X POST \
	https://a.b2benrich.com/api/contacts/create \
	-d '(
		{
			"organization_id": "org_...",
			"audience_id": "aud_...",
			"first_name": "Ada",
			"last_name": "Lovelace"
		}
	)'

Error responses

If your request body doesn’t match the schema, the API returns 422 Validation Error.

If your API key is missing or invalid, you should expect an authentication error response (for example 401 Unauthorized), depending on the gateway configuration.