Skip to main content

​
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 conceptAPI name
CRM campaign/listlist
Creator saved to a listcontact
Creator IDuser_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

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

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

​
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

EndpointDescription
GET /api/v2/crm/listsList your CRM lists.
POST /api/v2/crm/listsCreate 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}/creatorsList creators saved to a CRM list.
POST /api/v2/crm/lists/{list_id}/creatorsAdd one or more creators to a CRM list.
POST /api/v2/crm/lists/{list_id}/creators/checkCheck 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.