List scheduled reports

Overview

See every scheduled email report for your partner or an account.

Use this to manage them, and to find the report_id you need to edit or delete one.

You'll need a token.

Returns one entry per report, a page at a time.

Prerequisites

A bearer token. See Authentication.

Base URL

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

Endpoint

POST /api/v1/email-report/list

Authentication

Partner or Account token

The list covers only the reports of the company behind the token: a Partner token sees your partner's reports, an Account token sees its own account's reports.
If the user behind the token has no company, the list is empty.

Rate limit

60 requests per minute, counted per user (the token’s user). See Rate limits.

Request parameters

None.

Request body

All fields are optional.

Field	Type	Required	Description
`sort_field`	string	No	Field to sort by: `first_name`, `last_name`, `email`, `report_type` or `report_period_type_id`.
`sort_by`	string	No	Sort direction. Default `ASC`. Used only with `sort_field`.
`search_field`	string	No	Field to search: `first_name`, `last_name`, `email`, `report_type`, `report_period_type_id` or `store_name`. `report_type` and `report_period_type_id` match exactly; the others match part of the value. A `store_name` search also returns reports that cover every location.
`search_value`	string	No	The value to search for. Used only with `search_field`. Can't contain `<` or `>`.
`limit`	integer	No	Reports per page, 10 to 100. Values below 10 are raised to 10; above 100 returns `422`. Default 10.
`page`	integer	No	Page number. Default 1.

Request payload

{
  "sort_field": "email",
  "sort_by": "ASC",
  "search_field": "store_name",
  "search_value": "Sydney",
  "limit": 10
}

Response body

data is an array with one entry per report. links and meta carry the pagination.

Field	Type	Description
`data`	array of objects	The scheduled reports on this page. Disabled reports aren't listed.
`data[].id`	integer	The report's id. Use it as `report_id` to edit or delete the report.
`data[].first_name`	string or null	The recipient's first name, or `null`.
`data[].last_name`	string or null	The recipient's last name, or `null`.
`data[].email`	string or null	The recipient's email, or `null`.
`data[].report_type`	string	The report type, e.g. `activity_report` or `review_feed` (the `reportType` it was scheduled with).
`data[].report_period_type_id`	string	How often it's sent: `day`, `week` or `month`.
`data[].all_store`	integer	`1` when the report covers every location (or, for a partner report, every account); otherwise `0`.
`data[].store_list`	array of objects	The locations the report covers.
`data[].store_list[].value`	integer	The location's id (`store_id`).
`data[].store_list[].label`	string	The location's name, followed by `-` and its `client_location_id` (or its `storeid`).
`data[].account_list`	array of objects	The accounts a partner report covers.
`data[].account_list[].value`	integer	The account's id.
`data[].account_list[].label`	string	The account's name, followed by `-` and its `client_account_id` when it has one.
`links`	object	Links to the other pages.
`links.first`	string	URL of the first page.
`links.last`	string	URL of the last page.
`links.prev`	string or null	URL of the previous page, or `null` on the first page.
`links.next`	string or null	URL of the next page, or `null` on the last page.
`meta`	object	Pagination details.
`meta.current_page`	integer	The current page.
`meta.from`	integer or null	Position of the first row on this page, or `null` when the page is empty.
`meta.last_page`	integer	The last page number.
`meta.links`	array of objects	Page links, for building a pager.
`meta.links[].url`	string or null	URL of that page, or `null`.
`meta.links[].label`	string	Label for the link: a page number, `« Previous` or `Next »`.
`meta.links[].page`	integer or null	The page number, or `null` for a previous/next link that has no page.
`meta.links[].active`	boolean	Whether this is the current page.
`meta.path`	string	The endpoint URL, without the page query.
`meta.per_page`	integer	Rows per page.
`meta.to`	integer or null	Position of the last row on this page, or `null` when the page is empty.
`meta.total`	integer	Total rows across all pages.

Response payload

{
  "data": [
    {
      "id": 12,
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "[email protected]",
      "report_type": "activity_report",
      "report_period_type_id": "month",
      "all_store": 0,
      "store_list": [
        {
          "value": 3007,
          "label": "Acme Coffee - docs-test-loc-001"
        }
      ],
      "account_list": []
    }
  ],
  "links": {
    "first": "https://production-api.shoutaboutus.com/api/v1/email-report/list?page=1",
    "last": "https://production-api.shoutaboutus.com/api/v1/email-report/list?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "page": null,
        "active": false
      },
      {
        "url": "https://production-api.shoutaboutus.com/api/v1/email-report/list?page=1",
        "label": "1",
        "page": 1,
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "page": null,
        "active": false
      }
    ],
    "path": "https://production-api.shoutaboutus.com/api/v1/email-report/list",
    "per_page": 10,
    "to": 1,
    "total": 1
  }
}

Examples

Success payload

See Response payload.

No scheduled reports:

{
  "data": [],
  "links": {
    "first": "https://production-api.shoutaboutus.com/api/v1/email-report/list?page=1",
    "last": "https://production-api.shoutaboutus.com/api/v1/email-report/list?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": null,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "page": null,
        "active": false
      },
      {
        "url": "https://production-api.shoutaboutus.com/api/v1/email-report/list?page=1",
        "label": "1",
        "page": 1,
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "page": null,
        "active": false
      }
    ],
    "path": "https://production-api.shoutaboutus.com/api/v1/email-report/list",
    "per_page": 10,
    "to": null,
    "total": 0
  }
}

Error payload

422 Invalid sort or search

{
  "message": "The selected sort field is invalid. (and 3 more errors)",
  "errors": {
    "sort_field": [
      "The selected sort field is invalid."
    ],
    "sort_by": [
      "The selected sort by is invalid."
    ],
    "search_field": [
      "The selected search field is invalid."
    ],
    "search_value": [
      "Search_value field cannot contain < or >, or invalid characters"
    ]
  }
}

422 limit above 100

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

429 Too many requests

{
  "message": "Too Many Attempts."
}

Status	Meaning
`200`	The scheduled reports, a page at a time.
`401`	The token is missing, expired or invalid.
`422`	`sort_field`, `sort_by` or `search_field` isn't an allowed value, `search_value` contains `<` or `>`, or `limit` is above 100.
`429`	More than 60 requests in a minute from this user.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/email-report/list" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"sort_field": "email", "sort_by": "ASC", "search_field": "store_name", "search_value": "Sydney", "limit": 10}'

Updated 17 days ago

Did this page help you?