Fans

List the fans of an account

GET/v1/accounts/{account_id}/fans

Lists the fans this account has a conversation with, most recent first. Each item includes the current assignment, AI-lock state and tags. All filters are optional and combine with AND; values inside one list combine with OR. Spend and purchase filters count à-la-carte purchases only (tips, private media, pushes; subscriptions excluded, refunds excluded).

Required scoperead:fans

Rate limit30 requests per minute

curl 'https://api.fansquare.so/v1/accounts/c851d9d6-b90b-4958-aed2-2fdaa2fe21a3/fans' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Fansquare-Version: Amethyste"

{
  "data": [
    {
      "fan_id": "a6df8022-e509-4575-ad28-e29c2d1d42dc",
      "fan_username": "alex_92",
      "assigned_user_id": "ki9DZXxpgGz7KiDqHj88eCxHg56W",
      "ai_active": true,
      "tags": [
        {
          "id": "58368a92-838b-4cb0-ab37-d54ce826ea11",
          "name": "VIP"
        }
      ]
    }
  ],
  "next_cursor": "KI7cfD0OLcWfeXZb1FTusJpz0nfKiYXPwHCZe-VXBaeQSX1w5BvO5UH-ua-dzNpXOTixzw"
}

Parameters

Headers

Fansquare-Versionstringrequired
API version to pin. Accepts the mineral name or the release date of a version.

Path

account_idstringrequired
MYM account id (account.external_id in GET /v1/creators).
min length 1

Query

assigned_user_idsstring
Restrict to relations assigned to these employees (Fansquare user ids from GET /v1/employees). Comma-separated, 50 max.
tag_idsstring
Restrict to fans carrying at least one of these tags (Fansquare tag ids from GET /v1/tags). An id that is not a tag of the agency returns 422 unknown_tag. Comma-separated, 50 max.
exclude_tag_idsstring
Exclude fans carrying any of these tags (Fansquare tag ids from GET /v1/tags). Fans without tags are kept. An id listed in both tag_ids and exclude_tag_ids returns 400. Comma-separated, 50 max.
has_tagsstring
true: only fans with at least one tag. false: only fans without any tag (cannot be combined with tag_ids).
Valuestruefalse
statusesstring
Restrict to these subscription statuses. Values: active_subscriber, former_subscriber, interested. Comma-separated, 50 max.
min_spend_centsinteger
Only fans whose total à-la-carte spend on this account is at least this amount, in euro cents (5000 = 50 €).
min 1
last_purchase_afterstring
Only fans whose last à-la-carte purchase is at or after this date (ISO 8601).
format date-time
last_purchase_beforestring
Only fans whose last à-la-carte purchase is before this date (ISO 8601). Fans who never purchased are not included.
format date-time
is_onlinestring
true: only fans currently online on MYM. false: only fans currently offline.
Valuestruefalse
cursorstring
Opaque cursor from the previous page (next_cursor).
limitinteger
Page size (1-200).
Default 50min 1max 200

Response

OK, application/json

dataarray of objectsrequired
fan_idstringrequired
MYM fan id.
fan_usernamestring | nullrequired
MYM username of the fan, when available.
assigned_user_idstring | nullrequired
Fansquare id of the assigned employee, or null. Resolve names with GET /v1/employees.
ai_activebooleanrequired
true while an AI currently holds the lock on this fan.
tagsarray of objectsrequired
Tags set on this fan in Fansquare. Empty when the fan has no tag. Full catalog with colors: GET /v1/tags.
idstringrequired
Fansquare tag id, from GET /v1/tags.
namestringrequired
Tag label, as shown on the fan card in Fansquare.
next_cursorstring | nullrequired

curl 'https://api.fansquare.so/v1/accounts/c851d9d6-b90b-4958-aed2-2fdaa2fe21a3/fans' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Fansquare-Version: Amethyste"

{
  "data": [
    {
      "fan_id": "a6df8022-e509-4575-ad28-e29c2d1d42dc",
      "fan_username": "alex_92",
      "assigned_user_id": "ki9DZXxpgGz7KiDqHj88eCxHg56W",
      "ai_active": true,
      "tags": [
        {
          "id": "58368a92-838b-4cb0-ab37-d54ce826ea11",
          "name": "VIP"
        }
      ]
    }
  ],
  "next_cursor": "KI7cfD0OLcWfeXZb1FTusJpz0nfKiYXPwHCZe-VXBaeQSX1w5BvO5UH-ua-dzNpXOTixzw"
}