> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fuseai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with lists

> Enrich, copy, derive, organise and push a list once it exists

[Building a list](/guides/build-a-list-from-search) and [uploading one](/guides/upload-your-contacts) get contacts into Fuse. This page is what you do with a list afterwards.

Everything here needs a key with the `lists` [scope](/concepts/scopes). Enrichment and CRM pushes spend credits; the rest do not.

## Enrich the contacts you have

`POST /business/lists/{listId}/enrich` fills in missing contact details for a list you already built. `mode` decides what to look for:

| `mode`            | Finds                               |
| ----------------- | ----------------------------------- |
| `email`           | Work email addresses                |
| `phone`           | Phone numbers                       |
| `phone_and_email` | Both                                |
| `demographics`    | Demographic and firmographic fields |

```bash theme={null}
curl -X POST https://api.tryfuse.ai/api/v1/business/lists/$LIST_ID/enrich \
  -u "$FUSE_API_KEY:" -H "Content-Type: application/json" \
  -d '{ "mode": "phone_and_email" }'
```

```json theme={null}
{
  "listIds": ["68a1f20b9c41d20014b3e901"],
  "mode": "phone_and_email",
  "totalContacts": 200,
  "estimatedMinutes": 10
}
```

It answers `202` and works in the background — `totalContacts` is what it will attempt and `estimatedMinutes` roughly how long. Follow the list's `completionStatus`, as in [long-running work](/concepts/long-running-work).

<Note>
  Enrichment bills per contact enriched, not per contact attempted: a contact whose email cannot be found does not cost. Check the balance with `GET /business/credits` first for a large list.
</Note>

## Copy rows into another list

`POST /business/lists/save-to-list` copies rows from one list into another, optionally enriching them on the way. `sourceListId` and `limit` are both required, so a copy is always bounded.

```bash theme={null}
curl -X POST https://api.tryfuse.ai/api/v1/business/lists/save-to-list \
  -u "$FUSE_API_KEY:" -H "Content-Type: application/json" \
  -d '{ "sourceListId": "'$SOURCE'", "listName": "Q3 shortlist", "limit": 500 }'
```

Name an existing list with `listId`, or pass `listName` to create one. Add `filters` to copy only the rows that match — the same row filters `GET /business/lists/{listId}/rows` takes.

## Turn contacts into companies

`POST /business/lists/{listId}/derive-company-list` builds a company list from the employers of a contact list.

```json theme={null}
{
  "list": { "id": "68a1f20b9c41d20014b3e977", "name": "Q3 fintech companies" },
  "sourceContacts": 412
}
```

`sourceContacts` is how many contacts were read, not how many companies came out — several contacts usually collapse into one company. Useful when a person-level search has found the right accounts and you now want to work them at company level.

<Warning>
  A source list still building answers `409 LIST_PROCESSING`. Wait for its `completionStatus` to settle and retry.
</Warning>

## Commit an import

An [upload](/guides/upload-your-contacts) is a two-step: send the file, then commit it once the column mapping is right.

```bash theme={null}
curl -X POST https://api.tryfuse.ai/api/v1/business/imports/$IMPORT_ID/commit \
  -u "$FUSE_API_KEY:" -H "Content-Type: application/json" \
  -d '{ "listName": "Conference leads", "mapping": { "Email": "Email", "First": "First Name" } }'
```

The commit answers `202` with the destination `listId`. Its `jobId` is a UUID that `GET /business/jobs/{jobId}` cannot read — follow the destination list instead.

## Push to your CRM

`POST /business/lists/{listId}/crm-push` sends a list's contacts into a connected CRM.

```json theme={null}
{ "crm": "hubspot", "listIds": ["68a1f20b9c41d20014b3e901"] }
```

The CRM has to be connected already — see [CRM sync](/crm/overview). A workspace with no connection answers `422`.

## Organise with folders

Folders group lists of one kind. `type` is required everywhere, and the kinds do not mix: `contactList`, `companyList`, `campaign`, `agent`.

| Call                                     | Does                                                                 |
| ---------------------------------------- | -------------------------------------------------------------------- |
| `GET /business/folders?type=contactList` | Lists the folders of that kind                                       |
| `POST /business/folders`                 | Creates one                                                          |
| `PATCH /business/folders/{folderId}`     | Renames one — send `name`, and `type` for a campaign or agent folder |
| `DELETE /business/folders/{folderId}`    | Deletes the folder only                                              |

<Note>
  Deleting a folder never deletes lists. They move back to the root, so a folder is safe to remove once you have stopped using it.
</Note>

## Fix one contact

Two calls work on a single contact rather than a whole list:

`PATCH /business/contacts/{contactId}` sets which address or number is the primary one, when a contact has several:

```json theme={null}
{ "contact": { "id": "68a1f2c89c41d20014b3e955", "primaryEmail": "ada@brightpay.com", "primaryPhone": "+14155552671" } }
```

`GET /business/contacts/{contactId}/activities` returns that contact's timeline — what was sent, opened, replied and called, newest activity paged with `limit` and `cursor`:

```json theme={null}
{
  "contactId": "68a1f2c89c41d20014b3e955",
  "activities": [{ "id": "68a2b1c09c41d20014b41a10", "channel": "email", "status": "replied" }]
}
```

It is the quickest way to answer "have we already talked to this person?" before adding them to another campaign.