Audience · API reference

GET/v1/subscribers

List subscribers#

Lists people who subscribed to the church's updates. Email addresses are personal data: keep the key server-side and give it only audience:read. The list is a bounded snapshot paged with limit and cursor.

Auth. A church API key. Needs the audience:read scope, or a wildcard that includes it (machine:read, machine:*, * on a partner key). A partner key can call it for a customer church by sending X-Folio-Church.

Limits. Responses carry RateLimit-Limit and RateLimit-Remaining; a 429 carries Retry-After.

Auth: Church API key
Scope: audience:read
Operation id: machineListSubscribers

Parameters

Parameters
Name	In	Description
`limit`	query	Items per page. (integer)
`cursor`	query	Opaque cursor from meta.next_cursor of the previous page. (string)
`X-Folio-Church`	header	Partner keys only: run this call as one of your customer churches (its org_ id or slug). The church must be one of yours, the key must be allowed to act for it, and plan checks run against that church. (string, e.g. org_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012)

Responses

200 Success. List subscribers.

200 example

{
  "status": true,
  "message": "subscribers",
  "data": [
    {
      "id": "sub_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012",
      "object": "subscriber",
      "email": "[email protected]",
      "status": "confirmed"
    }
  ],
  "meta": {
    "request_id": "req_b337770ecebe03b03a88a8998b59263d",
    "has_next": false,
    "has_prev": false
  }
}

400 The request could not be read.

400 example

{
  "status": false,
  "message": "the page cursor is not valid",
  "error": {
    "code": "invalid_argument",
    "status": 400,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

401 The key or session is missing, invalid or expired.

401 example

{
  "status": false,
  "message": "That API key is not valid or has expired.",
  "error": {
    "code": "unauthenticated",
    "status": 401,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

403 The credential lacks the scope, the church is suspended, the feature is not in the plan, or the address is not allowed.

403 example

{
  "status": false,
  "message": "That API key does not have the required scope.",
  "error": {
    "code": "permission_denied",
    "status": 403,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

404 The resource is not in this church.

404 example

{
  "status": false,
  "message": "That item is not in this church.",
  "error": {
    "code": "not_found",
    "status": 404,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

409 Conflict, including a duplicate Idempotency-Key still being processed.

409 example

{
  "status": false,
  "message": "A request with this Idempotency-Key is still running.",
  "error": {
    "code": "conflict",
    "status": 409,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

422 A field failed validation, or an Idempotency-Key was reused with a different body.

422 example

{
  "status": false,
  "message": "A field is not valid.",
  "error": {
    "code": "validation",
    "status": 422,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

429 Rate limited. Wait Retry-After seconds.

429 example

{
  "status": false,
  "message": "Too many requests. Wait before trying again.",
  "error": {
    "code": "rate_limited",
    "status": 429,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

500 Something went wrong. Quote error.request_id.

500 example

{
  "status": false,
  "message": "Something went wrong. Quote the request id to support.",
  "error": {
    "code": "internal",
    "status": 500,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

Code samples

curl -X GET "$FOLIO_API_URL/v1/subscribers" \
  -H "Authorization: Bearer $FOLIO_API_KEY"

Verified against API version 0.0.0-dev. Generated from the live OpenAPI document.