List Free Subscribers

Server URLloading...

GET

/api/v1/external/subscribers/free

Send

Authorization

Header

Query

Returns the people who signed up on your host but hold no subscription at all — they registered, or dropped off at checkout, and have not purchased yet. Use it to sync un-converted leads into your own CRM or email tool.

Free here describes the person, not the product — it has nothing to do with whether a product costs money to buy.

The two subscriber lists overlap; they are not a partition. Someone whose only subscription was granted free — a free offering they claimed, or a grant you gave them — appears in both this list and List Subscribers: a free grant does not disqualify them here, and their active subscription is real there. Only a subscription that was actually paid for removes someone from this list. De-duplicate on _id if you sync both.

No query parameters returns page 1 with 25 leads, every country, and no date restriction. Leads are ordered by signedUpAt descending, tie-broken by _id so that ordering within a page is deterministic. Pagination is offset-based, so a signup arriving mid-walk shifts later pages: de-duplicate on _id when paging, and pin signedUpBefore to the start of the walk if you need a fixed window. A page beyond the last returns an empty data array while total still reports every match.

How the boundary is drawn: a lead disappears from this list the moment they hold one subscription that progressed past an abandoned checkout — and that check spans the whole platform, not just your products, so someone who purchased from a different creator will not appear here. Abandoned checkouts and free grants do not disqualify anyone.

Filter rules:

• signedUpAfter and signedUpBefore are inclusive and must be supplied together, no more than 366 days apart. Omit both to search every lead.
• country matches the stored value exactly and is case-sensitive, with no normalization. Records store a two-letter ISO 3166-1 alpha-2 code almost without exception, so use IN, not India — a handful of legacy records hold a display name instead, and a few hold no country at all.
• search matches name, email, or phone case-insensitively and is interpreted as a regular expression, so pattern characters are live — escape them to match literally. A term such as priya.sharma also matches priya-sharma because . is a wildcard, and an email containing + needs it escaped as \+ to match that character. Must contain at least 2 non-whitespace characters; it is otherwise passed through exactly as supplied, with no trimming. A pattern that is not valid regular-expression syntax is rejected with SUBSCRIBER_INVALID_REQUEST rather than failing the query.

This read is safe to retry. Malformed parameters return the standard validation 400; contradictory combinations return SUBSCRIBER_INVALID_REQUEST.

Query Parameters

Header Parameters

Response Body

curl -X GET "https://api-prod-new.tagmango.com/api/v1/external/subscribers/free" \  -H "x-whitelabel-host: string"

{
  "data": [
    {
      "_id": "6659ca9e5f2acb7abfdcd8fd",
      "name": "Priya Sharma",
      "email": "priya.sharma@example.com",
      "country": "IN",
      "profilePicUrl": "https://tagmango.com/staticassets/avatar-placeholder.png-1612857612139.png",
      "phone": "9876543210",
      "dialCode": "+91",
      "signedUpAt": "2026-08-26T11:04:19.412Z"
    }
  ],
  "total": 128
}

{
  "code": 400,
  "type": "Bad Request",
  "statusMessage": "BAD_REQUEST",
  "errorCode": "SUBSCRIBER_INVALID_REQUEST",
  "message": "The filters cannot describe a coherent query. Send paired date bounds together and in order, keep any window within the allowed span, supply a search term of at least the minimum length, and omit a filter rather than sending it empty. The response message names the specific rule that failed.",
  "result": "The filters cannot describe a coherent query. Send paired date bounds together and in order, keep any window within the allowed span, supply a search term of at least the minimum length, and omit a filter rather than sending it empty. The response message names the specific rule that failed.",
  "success": false
}

{
  "code": 401,
  "type": "Unauthorized",
  "statusMessage": "UNAUTHORIZED",
  "message": "Invalid token",
  "result": "Invalid token",
  "success": false
}

{
  "code": 403,
  "type": "Forbidden",
  "statusMessage": "FORBIDDEN",
  "errorCode": "WORKSHOP_MANGO_FORBIDDEN",
  "message": "You can not access this api with a TagMango account, only available for whitelabel hosts",
  "result": "You can not access this api with a TagMango account, only available for whitelabel hosts",
  "success": false
}

{
  "code": 404,
  "type": "Not Found",
  "statusMessage": "NOT_FOUND",
  "errorCode": "SUBSCRIBER_HOST_NOT_FOUND",
  "message": "We could not resolve a creator for the authenticated host.",
  "result": "We could not resolve a creator for the authenticated host.",
  "success": false
}

{
  "code": 429,
  "type": "Too Many Requests",
  "statusMessage": "TOO_MANY_REQUESTS",
  "message": "Request limit exceeded. try after 10 seconds",
  "result": "Request limit exceeded. try after 10 seconds",
  "success": false
}

{
  "code": 500,
  "type": "UnknownError",
  "statusMessage": "INTERNAL_SERVER_ERROR",
  "errorCode": "SUBSCRIBER_LIST_FAILED",
  "message": "We could not load the subscribers. Please try again later.",
  "result": "We could not load the subscribers. Please try again later.",
  "success": false
}