List campaigns

Overview

Get the campaigns for an account, with status, channels, and send counts.

Use this to show campaigns in your own UI or to find a campaign_id.

Filter by status or location, or search by name; results are paginated.

Returns one entry per campaign.

Prerequisites

A bearer token. See Authentication.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

GET /api/v1/campaign/list

Authentication

Account token

Lists the campaigns of the account of the user behind the token.
A user limited to assigned locations only sees campaigns for those locations.

Rate limit

This endpoint has no rate limit.

Request parameters

Parameter	In	Type	Required	Description
`status`	query	string	No	`draft`, `active` (scheduled or in progress) or `inactive` (completed, paused or cancelled). Leave it out for all.
`location_id`	query	integer	No	Only campaigns for this location. Must be an existing location.
`search_field`	query	string	No	The field to search, used with `search_value`: `name`, `description`, `store_name`, `store_id`, `storeId` or `type`.
`search_value`	query	string	No	The text to search for, up to 255 characters. Matches part of the value, except for `store_id` and `type`, which must match exactly.
`sort_field`	query	string	No	The field to sort by. Default `created_at`. One of `name`, `status`, `created_at`, `updated_at`, `scheduled_at`, `started_at`, `completed_at`, `request_file_status`, `request_per_day`, `request_frequency`, `request_delay`, `next_execution_time`, `total_audience`, `total_valid_phones`, `total_valid_emails`, `store_name`, `storeId`, `type`.
`sort_by`	query	string	No	`asc` or `desc` (either case). Default `desc`.
`page`	query	integer	No	The page to return, from `1`. Default `1`.
`per_page`	query	integer	No	Campaigns per page, `10`–`100`. Default `15`. Values below 10 are raised to 10; above 100 returns `422`.

Request body

None.

Request payload

None.

Response body

The payload is inside data: a page of campaigns, with the paging fields beside it.

Field	Type	Description
`data`	array of objects	The campaigns, newest first by default. An empty array `[]` when none match.
`data[].id`	integer	The campaign's id (`campaign_id`).
`data[].store_id`	integer	The campaign's location.
`data[].user_id`	integer	The user who created the campaign.
`data[].name`	string	The campaign's name.
`data[].description`	string or null	The campaign's description, or `null`.
`data[].status`	string	`draft`, `scheduled`, `in_progress`, `paused`, `completed` or `cancelled`.
`data[].current_step`	integer	The furthest wizard step reached, `1` to `4`.
`data[].scheduled_at`	string or null	When the campaign was scheduled, or `null`.
`data[].started_at`	string or null	When sending started, or `null`.
`data[].completed_at`	string or null	When the campaign finished, or `null`.
`data[].total_audience`	integer	Recipients on the campaign, not counting test sends.
`data[].total_valid_phones`	integer	Recipients with a valid phone number, not counting test sends.
`data[].total_valid_emails`	integer	Recipients with a valid email address, not counting test sends.
`data[].request_file_name`	string or null	Name of the uploaded recipient file, or `null`.
`data[].request_file_status`	string	`pending`, `processing`, `completed` or `failed`.
`data[].request_per_day`	integer	Most requests sent a day.
`data[].request_frequency`	integer	`0` every day, `1` every other day, `2` once a week, `3` once every two weeks, `4` once a month.
`data[].request_delay`	integer	Days to wait before the first request.
`data[].request_after_time`	string	Time of day requests are sent, in UTC.
`data[].next_execution_time`	string or null	When the next batch is due, or `null`.
`data[].send_immediately`	boolean	`true` when the first send was scheduled for launch time.
`data[].type`	string or null	`bulk_upload`, `automation` or `kiosk`; `null` until set.
`data[].created_at`	string	When the campaign was created.
`data[].updated_at`	string	When the campaign last changed.
`data[].channels`	array of objects	The campaign's email and SMS channels.
`data[].channels[].id`	integer	The channel's id (`channel_id`).
`data[].channels[].rs_campaign_id`	integer	The campaign the channel belongs to.
`data[].channels[].channel_type`	string	`email` or `sms`.
`data[].channels[].is_enabled`	boolean	Whether the channel is on.
`data[].channels[].template_id`	integer or null	The attached template, or `null`.
`data[].channels[].errors`	object	Review sites the channel's template or landing page links to that the location isn't set up for: `review_site_not_found` (no URL saved for the site) and `landing_page_url_not_found` (no landing page URL), each a list of `{review_site_id, review_site_name}`. An empty array `[]` when there are none.
`data[].channels[].landing_page`	object	For an SMS channel, `{ "id": … }`: the landing page of its template. An empty array `[]` for an email channel.
`data[].store`	object or null	The campaign's location, or `null` if it no longer exists.
`data[].store.id`	integer	The location's id.
`data[].store.name`	string	The location's name.
`data[].store.storeId`	string or null	Your own reference for the location, or `null`.
`data[].store.clientLocationId`	string or null	The client location id, or `null`.
`data[].request_file_url`	string or null	URL of the uploaded recipient file, or `null`.
`data[].unique_code`	string	The campaign's unique code (used by kiosk sends).
`data[].has_sms_channel`	boolean	`true` when the SMS channel is on.
`data[].has_email_channel`	boolean	`true` when the email channel is on.
`data[].is_active`	boolean	`true` when `status` is `scheduled` or `in_progress`.
`current_page`	integer	The page returned.
`per_page`	integer	Campaigns per page.
`total`	integer	Campaigns matching the filters, across all pages.
`last_page`	integer	The last page number.
`from`	integer or null	Position of the first campaign on this page, or `null` when the page is empty.
`to`	integer or null	Position of the last campaign on this page, or `null` when the page is empty.
`first_page_url`	string	URL of the first page.
`last_page_url`	string	URL of the last page.
`prev_page_url`	string or null	URL of the previous page, or `null`.
`next_page_url`	string or null	URL of the next page, or `null`.
`path`	string	The endpoint URL without the query string.
`links`	array of objects	Page links for a pager.
`links[].url`	string or null	The link's URL, or `null` when there is no such page.
`links[].label`	string	The link's label, e.g. `1` or `Next »`.
`links[].page`	integer or null	The page number, or `null`.
`links[].active`	boolean	`true` for the current page.

Response payload

{
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 4824,
        "store_id": 3007,
        "user_id": 3011,
        "name": "Summer Review Campaign",
        "description": null,
        "status": "draft",
        "current_step": 1,
        "scheduled_at": null,
        "started_at": null,
        "completed_at": null,
        "total_audience": 0,
        "total_valid_phones": 0,
        "total_valid_emails": 0,
        "request_file_name": null,
        "request_file_status": "pending",
        "request_per_day": 50,
        "request_frequency": 0,
        "request_delay": 0,
        "request_after_time": "14:00",
        "next_execution_time": null,
        "send_immediately": false,
        "type": null,
        "created_at": "2026-10-01T08:02:47.000000Z",
        "updated_at": "2026-10-01T08:02:47.000000Z",
        "channels": [],
        "store": {
          "id": 3007,
          "name": "Acme Coffee",
          "storeId": null,
          "clientLocationId": null
        },
        "request_file_url": null,
        "unique_code": "3r2mto",
        "has_sms_channel": false,
        "has_email_channel": false,
        "is_active": false
      },
      {
        "id": 4823,
        "store_id": 3007,
        "user_id": 3011,
        "name": "Spring Review Campaign",
        "description": null,
        "status": "draft",
        "current_step": 1,
        "scheduled_at": null,
        "started_at": null,
        "completed_at": null,
        "total_audience": 1,
        "total_valid_phones": 0,
        "total_valid_emails": 1,
        "request_file_name": null,
        "request_file_status": "pending",
        "request_per_day": 5,
        "request_frequency": 0,
        "request_delay": 0,
        "request_after_time": "21:00:00",
        "next_execution_time": null,
        "send_immediately": false,
        "type": "kiosk",
        "created_at": "2026-10-01T08:02:04.000000Z",
        "updated_at": "2026-10-01T08:02:08.000000Z",
        "channels": [
          {
            "id": 5393,
            "rs_campaign_id": 4823,
            "channel_type": "email",
            "is_enabled": true,
            "template_id": 9083,
            "errors": [],
            "landing_page": []
          }
        ],
        "store": {
          "id": 3007,
          "name": "Acme Coffee",
          "storeId": null,
          "clientLocationId": null
        },
        "request_file_url": null,
        "unique_code": "9445a2",
        "has_sms_channel": false,
        "has_email_channel": true,
        "is_active": false
      }
    ],
    "first_page_url": "https://production-api.shoutaboutus.com/api/v1/campaign/list?page=1",
    "from": 1,
    "last_page": 1,
    "last_page_url": "https://production-api.shoutaboutus.com/api/v1/campaign/list?page=1",
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "page": null,
        "active": false
      },
      {
        "url": "https://production-api.shoutaboutus.com/api/v1/campaign/list?page=1",
        "label": "1",
        "page": 1,
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "page": null,
        "active": false
      }
    ],
    "next_page_url": null,
    "path": "https://production-api.shoutaboutus.com/api/v1/campaign/list",
    "per_page": 10,
    "prev_page_url": null,
    "to": 2,
    "total": 2
  }
}

Examples

Success payload

Draft campaigns (?status=draft&per_page=10): see Response payload.

No campaigns match the filters:

{
  "data": {
    "current_page": 1,
    "data": [],
    "first_page_url": "https://production-api.shoutaboutus.com/api/v1/campaign/list?page=1",
    "from": null,
    "last_page": 1,
    "last_page_url": "https://production-api.shoutaboutus.com/api/v1/campaign/list?page=1",
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "page": null,
        "active": false
      },
      {
        "url": "https://production-api.shoutaboutus.com/api/v1/campaign/list?page=1",
        "label": "1",
        "page": 1,
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "page": null,
        "active": false
      }
    ],
    "next_page_url": null,
    "path": "https://production-api.shoutaboutus.com/api/v1/campaign/list",
    "per_page": 10,
    "prev_page_url": null,
    "to": null,
    "total": 0
  }
}

Error payload

422 Invalid filter value

{
  "message": "The selected status is invalid. (and 1 more error)",
  "errors": {
    "status": [
      "The selected status is invalid."
    ],
    "sort_by": [
      "The selected sort by is invalid."
    ]
  }
}

422 per_page above 100

{
  "message": "The per page field must not be greater than 100.",
  "errors": {
    "per_page": [
      "The per page field must not be greater than 100."
    ]
  }
}

Status	Meaning
`200`	A page of campaigns, or an empty `data` array when none match.
`401`	The token is missing, expired or invalid.
`422`	A filter value isn't allowed, `location_id` doesn't exist, or `per_page` is above 100.
`500`	Unexpected server error.

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/campaign/list?status=draft&per_page=10" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'