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.

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:

TO_OUTREACH
OUTREACHED
NEGOTIATING
WORKING
DONE
CANCELLED

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

Common workflow

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

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"
  }'

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;

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"
  }'

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',
  }),
});

Response envelope

All CRM API responses use the standard public API envelope:

{
  "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.

CRM API v2

CRM API v2

Base URL

Authentication

Pricing

Rate limits

CRM lists

Status values

Common workflow

Response envelope

Endpoints

Lists

List CRM Lists

Create CRM List

Get CRM List

Update CRM List

Delete CRM List

Creators

List CRM Creators

Add Creators to CRM List

Check CRM List Membership

Remove Creator from CRM List

Update CRM Contact

​CRM API v2

​Base URL

​Authentication

​Pricing

​Rate limits

​CRM lists

​Status values

​Common workflow

​Response envelope

​Endpoints

Lists

List CRM Lists

Create CRM List

Get CRM List

Update CRM List

Delete CRM List

Creators

List CRM Creators

Add Creators to CRM List

Check CRM List Membership

Remove Creator from CRM List

Update CRM Contact

CRM API v2

Base URL

Authentication

Pricing

Rate limits

CRM lists

Status values

Common workflow

Response envelope

Endpoints