> 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/dataset-api.md).

# Dataset API

The Dataset API gives your systems access to the companies, contacts and data maintained in your Goodfit dataset.

Use it when you want to bring Goodfit data into your own systems, keep another system in sync, or check what Goodfit already knows about a company.

> This API reads from **your Goodfit dataset**, rather than every company Goodfit knows about.\
> To add or enrich a company that is not already in your dataset, use the [**Company Enrichment API**](https://docs.goodfit.io/goodfit-docs/apis/enrichment-api/companies).

### Common use cases

#### Keep your CRM or data warehouse in sync

Use the Dataset API [list companies API](https://docs.goodfit.io/goodfit-docs/apis/dataset-api/companies#get-dataset-companies) to continuously copy changes from Goodfit into another system.

Typical examples include:

* Keeping company records in your CRM up to date.
* Updating contact records when Goodfit finds new information.
* Feeding Goodfit data into your warehouse or BI platform.
* Maintaining your own internal account or contact index.

For ongoing synchronisation, use `updated_since` to retrieve records that have changed since your previous successful sync.

Use `added_since` when you only care about records newly added to your dataset.

#### Check whether a company is already in your dataset

Look up a [company by domain](https://docs.goodfit.io/goodfit-docs/apis/dataset-api/companies#get-dataset-companies-domain) when you need to determine whether Goodfit already has it.

This is useful in workflows such as:

1. A company enters your product, CRM or enrichment workflow.
2. Check the Dataset API for the company.
3. If it exists, use the current Goodfit record.
4. If it does not exist, send it to the Company Enrichment API.

This pattern avoids enriching companies you already have.

#### Retrieve companies for a campaign or workflow

You can [search the companies](https://docs.goodfit.io/goodfit-docs/apis/dataset-api/companies#post-dataset-companies-search) in your dataset using the same types of data points you use in Goodfit and our [filter defintions](https://docs.goodfit.io/goodfit-docs/apis/dataset-api/filters).

For example:

* Companies in a particular country.
* Companies above a given employee count.
* Companies matching your Goodfit market or scoring criteria.
* Companies with particular firmographic, hiring or technology characteristics.

Use the company fields endpoint to discover the fields and filtering operators available for your dataset.

#### Retrieve contacts for companies

Where contacts are enabled, the Dataset API can be used to [retrieve contacts](https://docs.goodfit.io/goodfit-docs/apis/dataset-api/contacts#get-dataset-contacts) from your Goodfit dataset.

Common patterns include:

* Getting all contacts for a particular company.
* Synchronising contacts into a CRM.
* Passing qualified contacts into an outbound workflow.
* Updating existing contact records when information changes.

Contacts include a stable identifier that can be used when upserting them into another system.

#### Download your full dataset

For large or one-off downloads, use the [Exports API](https://docs.goodfit.io/goodfit-docs/apis/dataset-api/exports) rather than paginating through every record.

An export can contain:

* `companies.csv`
* `contacts.csv`, where contacts are enabled

Exports are generated asynchronously, so the usual pattern is:

1. Request an export.
2. Check its status until it completes.
3. Request temporary download URLs.
4. Download the generated files.

This is the recommended approach for large full-dataset extracts.

### Integration patterns

#### Incremental sync

For most ongoing integrations, use an incremental sync rather than repeatedly downloading the entire dataset.

A typical flow is:

1. Record the time immediately before starting a sync.
2. [Request companies](https://docs.goodfit.io/goodfit-docs/apis/dataset-api/companies#get-dataset-companies) using the timestamp from your previous successful sync as `updated_since` query parameter.
3. Follow pagination until all records have been retrieved.
4. Repeat for contacts if required.
5. Once the sync completes successfully, store the timestamp captured in step 1.
6. Use that timestamp on the next sync.

Capturing the timestamp **before** the sync starts prevents updates made while the sync is running from being missed.

Use `added_since` instead if your integration only needs newly added records.

#### Lookup first, enrich second

A common enrichment workflow combines the Dataset API with the Company Enrichment API:

```
Company enters workflow
        ↓
Check Dataset API lookup company by domain
        ↓
 ┌──── already exists ────→ Use existing Goodfit record
 │
 └──── not found ─────────→ Company or contact Enrichment API
                                   ↓
                              Enriched company
                                   ↓
                          Added to Goodfit dataset
```

This is useful for inbound leads, account creation, CRM workflows and enrichment waterfalls.

#### Full initial load followed by incremental updates

For a new integration, a useful pattern is:

```
Initial CSV export
        ↓
Load into CRM / warehouse
        ↓
Store sync timestamp
        ↓
Incremental API syncs using updated_since
```

This avoids making a large number of API requests for the initial dataset while still allowing the integration to stay current afterwards.

You can use this example to request an incremental export:

```
curl --request POST \
  --url 'https://api.goodfit.io/dataset/exports' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "exportConfig": {
      "filters": {
        "id": "root",
        "combinator": "and",
        "rules": [
          {
            "id": "updated-since",
            "field": "__updated_at",
            "operator": "dateSince",
            "value": "XXXX-XXX-XX"
          }
        ]
      }
    }
  }'
```

#### Working with custom dataset fields

Company records reflect the fields configured in your Goodfit dataset, so their exact schema can vary between accounts.

This may include:

* Goodfit markets
* Scores
* Firmographic data
* Hiring data
* Technology data
* Custom data points

Use the [company data points](https://docs.goodfit.io/goodfit-docs/apis/dataset-api/companies#get-dataset-companies-fields) endpoint to discover which fields are available before building dynamic filtering or mapping logic.

System fields such as company IDs and added/updated timestamps can be used as stable identifiers and sync metadata.

### API reference

The Dataset API is split into separate reference sections for companies, contacts and exports.

* [Companies](/goodfit-docs/apis/dataset-api/companies.md)
* [Contacts](/goodfit-docs/apis/dataset-api/contacts.md)
* [Exports](/goodfit-docs/apis/dataset-api/exports.md)