Promoters

List promoters with cursor-based pagination

Changed on

Returns promoters with cursor pagination. Filter by teamId to see promoters for a specific team.

get/promoters

Request

  • Base URL: https://api.session.services
  • URL: https://api.session.services/promoters
  • Auth: API key in header x-tenant-id

Query parameters

teamIdstring

Filter promoters to only those belonging to a specific team

approval'PENDING' | 'APPROVED' | 'REJECTED'

Filter promoters by approval status. PENDING: awaiting review, APPROVED: can create events, REJECTED: cannot operate

Example:APPROVED
querystring

Optional search query. When provided, results are fetched from search with unified cursor pagination.

Example:Session Services
latitudenumber

Latitude used with longitude and radius to filter promoters by proximity when searching.

Example:-33.8944593
longitudenumber

Longitude used with latitude and radius to filter promoters by proximity when searching.

Example:151.2252255
radiusnumber

Search radius in kilometers applied when latitude and longitude are provided.

Example:50
mineboolean

When true, limits results to promoters from teams the current user belongs to. When combined with teamId, returns only that team's promoters (bypassing tenant-wide admin scope).

Example:true
sort'createdAt'

Optional list sort field. Use createdAt to return newest or oldest promoters first.

Example:createdAt
direction'asc' | 'desc'

Sort direction for promoter lists. Defaults to desc when omitted.

Example:desc
limitnumber

Maximum number of promoters to return (1-100, defaults to 20)

Example:20
cursorstring

Opaque cursor for pagination. Use the cursor from the previous response to continue fetching results.

Example:eyJpZCI6InByb18wMWpxcGprc25zZW45dnBydzk1ZXQ2MHQybSJ9

Response

OK

beforestring nullable

Cursor for navigating backward in the result set. Omitted when there are no prior results.

afterstring nullable

Cursor for navigating forward in the result set. Omitted when there are no subsequent results.

limitnumber required

Maximum number of items to return in each result set

Example response

{
  "promoters": [
    {
      "id": "pmt_01jqpjksnsen9vprw95et60t2m",
      "createdAt": "2026-10-17T08:46:46.696Z",
      "updatedAt": "2026-10-17T08:46:46.696Z",
      "name": "Session Services",
      "slug": "session-services",
      "teamId": "tem_01jqpjksnsen9vprw95et60t2m",
      "description": "This is only a test...",
      "approval": "APPROVED",
      "image": {
        "src": "https://assets.session.services/my-image.jpg",
        "alt": "My Image",
        "width": 1080,
        "height": 1080
      },
      "location": {
        "id": "loc_01hk153x00eh99pagyydz03sbz",
        "googlePlaceId": "ChIJP3Sa8ziYEmsRUKgyFmh9AQM",
        "createdAt": "2026-10-17T08:46:46.696Z",
        "updatedAt": "2026-10-17T08:46:46.696Z",
        "name": "Watson's EQ",
        "address": "The, Entertainment Quarter, 1 Bent St, Moore Park NSW 2021, Australia",
        "city": "Moore Park",
        "state": "New South Wales",
        "postcode": "2021",
        "country": "Australia",
        "latitude": -33.8944593,
        "longitude": 151.2252255,
        "timeZone": "Australia/Sydney",
        "types": [
          "establishment",
          "point_of_interest",
          "stadium"
        ],
        "description": "Historic outdoor amphitheater known for summer concerts",
        "image": {
          "src": "https://assets.session.services/my-image.jpg",
          "alt": "My Image",
          "width": 1080,
          "height": 1080
        },
        "venue": {
          "image": {
            "src": "https://assets.session.services/my-image.jpg",
            "alt": "My Image",
            "width": 1080,
            "height": 1080
          }
        }
      },
      "geohash": "r3gx1",
      "tracking": {
        "fbId": "485739562847563",
        "gaId": "G-PSW1MY7HB4",
        "tikTokId": "BQCKPH3RC77U8GPMLJ5G"
      }
    }
  ],
  "before": "eyJ2ZXJzaW9uIjoxLCJpbnRlbnQiOnsic291cmNlIjoiZGVtbyJ9LCJwb3MiOnsicHJpbWFyeUtleSI6InBybV8wMXM4NTNqIn19",
  "after": "eyJ2ZXJzaW9uIjoxLCJpbnRlbnQiOnsic291cmNlIjoiZGVtbyJ9LCJwb3MiOnsicHJpbWFyeUtleSI6InBybV8wMXM4NTNkIn19",
  "limit": 20
}

Changes

  • 84f157e4443aRevision changes
    • info

      added the non-success response with the status

  • a50002a612e2Revision changes
    • warning

      for the query request parameter cursor, the maxLength was set to 768

    • warning

      for the query request parameter query, the maxLength was set to 120

    • warning

      for the query request parameter teamId, the maxLength was set to 128

    • warning

      for the query request parameter radius, the max was set to 20000.00

    • warning

      for the query request parameter radius, the min was set to 1.00