> For the complete documentation index, see [llms.txt](https://docs.goodfit.io/goodfit-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.goodfit.io/goodfit-docs/apis/apis-introduction.md).

# 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.

<figure><img src="https://1640582697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMPh5iOobj4telctyJWpa%2Fuploads%2FFB8m7c3Zf39VdNSnFuM9%2FScreenshot%202026-09-29%20at%2010.47.56.png?alt=media&amp;token=b4ea7458-5b4e-4774-afd9-85d5d6e0a733" alt=""><figcaption></figcaption></figure>

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:

```http
Authorization: YOUR_API_KEY
```

For example:

```bash
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:

```http
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.

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

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