APIs introduction

All Goodfit APIs use the same base URL and authentication method.

Base URL

https://api.goodfit.io

Each API has its own path:

API	Base path
Dataset API	/dataset
Enrichment API	/enrichment

For example:

https://api.goodfit.io/dataset/companies
https://api.goodfit.io/enrichment/enrich
https://api.goodfit.io/enrichment/enrich-contact/request

Getting an API key

API access must first be enabled for your Goodfit account. Contact your Account Manager if you would like access to one or more Goodfit APIs.

Once access has been granted, you can create and manage API keys in Goodfit:

Settings → API Keys → Create API Key

When creating a key:

• Give it a clear Display Name so you can identify where it is being used.

• Select the API scopes the key should have access to.

• Only grant the scopes required for that integration.

• Create separate API keys for different systems or environments where practical.

Available scopes depend on the APIs enabled for your account and may include:

Scope	Access
Enrichment API	Enrichment API (companies)
Client Data API	Dataset API
Contact Enrichment API	Enrichment API (contacts)

The API Keys page also shows your existing keys, their scopes, creation date and status. Keys that are no longer required can be revoked from this page.

Authentication

All API requests require a Goodfit API key.

Send your API key in the Authorization header on every request:

Authorization: YOUR_API_KEY

For example:

curl --request GET \
  --url https://api.goodfit.io/dataset/companies \
  --header 'Authorization: YOUR_API_KEY'

Keep API keys secret

API keys provide access to your Goodfit data and APIs and should be treated as secrets.

Do not:

• Expose API keys in client-side or browser code.

• Commit API keys to source control.

• Include API keys in publicly accessible configuration or logs.

• Share API keys over unsecured channels.

Store keys using your application's secret or credential management system, such as environment variables or a managed secrets service.

If you believe a key has been exposed, revoke it from Settings → API Keys and create a replacement key.

Authentication errors

Status	Meaning
401 Unauthorized	The Authorization header is missing or malformed
403 Forbidden	The API key is unknown, revoked, or does not have access to the requested API

Rate limits

Rate limits are applied at account level and are shared across API keys belonging to the same account.

API	Rate limit
Dataset API	20 requests per second
Enrichment API (companies)	20 requests per second
Enrichment API (contacts)	20 requests per second

If you exceed a rate limit, the API returns:

429 Too Many Requests
Retry-After: 1

The Retry-After header gives the number of seconds to wait before making another request.

Applications should honour this header and retry the request after the specified delay. A 429 response is temporary and does not indicate that the request itself is invalid.

For integrations making requests concurrently, apply rate limiting across the whole Goodfit account rather than independently for each API key.

HTTP errors

Goodfit uses standard HTTP status codes.

Status	Meaning
400 Bad Request	The request or one of its parameters is invalid
401 Unauthorized	Authentication is missing or malformed
403 Forbidden	The API key is invalid, revoked, or does not have access
404 Not Found	The requested resource could not be found
429 Too Many Requests	The account's rate limit has been exceeded
500 Internal Server Error	An unexpected error occurred

Where an API returns a machine-readable error code, integrations should use that value rather than depending on the exact wording of the human-readable error message.

{
  "error": "Bad request: Invalid request",
  "code": "INVALID_REQUEST"
}

Individual API reference pages document any additional status codes and error conditions specific to those endpoints.