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

# CRM API v2

> Create CRM lists and manage saved creators from your own systems

# CRM API v2

The CRM API lets you manage the same creator lists your team uses in the TopYappers app. Use it to create lists, add creators from the Creators API, check whether creators are already saved, move contacts through outreach statuses, and remove creators from a list.

## Base URL

`https://api.topyappers.com`

## Authentication

All requests require a TopYappers API key in the `x-ty-api-key` header.

```bash theme={null}
x-ty-api-key: your-api-key
```

The API key is scoped to the key owner's team, so CRM lists and contacts are only read or changed inside that team.

The API key must belong to a user with an active TopYappers subscription. CRM endpoints are free to call, but they are not available to inactive subscriptions.

## Pricing

CRM API endpoints are **free for active subscribers**. They validate your API key and subscription status and apply rate limits, but they do not consume credits because they manage your own CRM data.

Use `GET /api/v2/creators/search` and `POST /api/v2/creators/get` when you need to discover creators or fetch full creator profiles.

## Rate limits

* 60 requests per minute per API key.
* HTTP `429` responses include `Retry-After`.
* Responses include `x-ty-rate-limit-remaining`, `x-ty-rate-limit-total`, and `x-ty-credits` headers.

## CRM lists

In the API, CRM campaigns are exposed as **lists**.

| App concept             | API name  |
| ----------------------- | --------- |
| CRM campaign/list       | `list`    |
| Creator saved to a list | `contact` |
| Creator ID              | `user_id` |

## Status values

Use these values for `status`:

```text theme={null}
TO_OUTREACH
OUTREACHED
NEGOTIATING
WORKING
DONE
CANCELLED
```

Status input is case-insensitive, so `outreached` is accepted and stored as `OUTREACHED`.

## Common workflow

1. Find creator IDs with `GET /api/v2/creators/search`.
2. Create a CRM list with `POST /api/v2/crm/lists`.
3. Add creators with `POST /api/v2/crm/lists/{list_id}/creators`.
4. Check membership with `POST /api/v2/crm/lists/{list_id}/creators/check`.
5. Update outreach stage with `PATCH /api/v2/crm/contacts/{contact_id}`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.topyappers.com/api/v2/crm/lists" \
    -H "Content-Type: application/json" \
    -H "x-ty-api-key: $TY_API_KEY" \
    -d '{
      "name": "June outreach"
    }'
  ```

  ```javascript JavaScript theme={null}
  const listRes = await fetch('https://api.topyappers.com/api/v2/crm/lists', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-ty-api-key': process.env.TY_API_KEY,
    },
    body: JSON.stringify({ name: 'June outreach' }),
  });

  const listPayload = await listRes.json();
  const listId = listPayload.response.id;
  ```
</CodeGroup>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.topyappers.com/api/v2/crm/lists/$LIST_ID/creators" \
    -H "Content-Type: application/json" \
    -H "x-ty-api-key: $TY_API_KEY" \
    -d '{
      "userIds": [
        "instagram_57971538386",
        "instagram_58848167468"
      ],
      "status": "TO_OUTREACH",
      "notes": "Imported from June creator search"
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch(`https://api.topyappers.com/api/v2/crm/lists/${listId}/creators`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-ty-api-key': process.env.TY_API_KEY,
    },
    body: JSON.stringify({
      userIds: ['instagram_57971538386', 'instagram_58848167468'],
      status: 'TO_OUTREACH',
      notes: 'Imported from June creator search',
    }),
  });
  ```
</CodeGroup>

## Response envelope

All CRM API responses use the standard public API envelope:

```json theme={null}
{
  "message": "OK",
  "response": {
    "data": []
  }
}
```

Paginated creator-list responses include `page`, `per_page`, `next_page`, `total_pages`, and `total` inside `response`.

## Endpoints

| Endpoint                                                | Description                                    |
| ------------------------------------------------------- | ---------------------------------------------- |
| `GET /api/v2/crm/lists`                                 | List your CRM lists.                           |
| `POST /api/v2/crm/lists`                                | Create a CRM list.                             |
| `GET /api/v2/crm/lists/{list_id}`                       | Get a CRM list.                                |
| `PATCH /api/v2/crm/lists/{list_id}`                     | Update a CRM list.                             |
| `DELETE /api/v2/crm/lists/{list_id}`                    | Delete a CRM list.                             |
| `GET /api/v2/crm/lists/{list_id}/creators`              | List creators saved to a CRM list.             |
| `POST /api/v2/crm/lists/{list_id}/creators`             | Add one or more creators to a CRM list.        |
| `POST /api/v2/crm/lists/{list_id}/creators/check`       | Check whether creator IDs exist in a CRM list. |
| `DELETE /api/v2/crm/lists/{list_id}/creators/{user_id}` | Remove a creator from a CRM list.              |
| `PATCH /api/v2/crm/contacts/{contact_id}`               | Update CRM contact status and details.         |