Schedule an account email report

Overview

Set up a recurring email report for a business owner or user.

Use this to give a customer a regular digest.

You'll need the user, schedule, and options.

The report is scheduled. The response doesn't include the new report's id; get it from List scheduled reports.

Prerequisites

An Account bearer token. See Authentication.
The report type and how often to send it, the locations to cover, and the recipient: an existing email, or a new recipient's email and name.

Base URL

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

Endpoint

POST /api/v1/user/reports/add

Authentication

Account token

Only Account tokens can call it. Any other token gets 403 (This action is unauthorized.).
The report belongs to your account. Each id in store_ids must be a location inside your account; anything else is rejected with 422. With all_store set to 1, every location you can see is covered.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Field	Type	Required	Description
`reportType`	string	Yes	The report to send: `activity_report`, `response_report`, `review_feed`, `review_feed_star`, `review_responses`, `review_site_connections` or `insight_report`.
`reportPeriodType`	string	Yes	How often to send it: `day`, `week` or `month`. Allowed values depend on `reportType`: `activity_report`, `response_report` and `insight_report` must be `month`; `review_feed` and `review_feed_star` must be `day`; `review_site_connections` must be `week` or `month`; `review_responses` accepts any. A wrong combination returns `422`.
`all_store`	integer	Yes	`1` to cover every location in your account, `0` to cover only the locations in `store_ids`.
`store_ids`	array of integers	When `all_store` is `0`	Location ids to cover. Required when `all_store` is `0`. Each must exist and be inside your account.
`old_recipient_email`	string	When `recipient_email` is missing	Email to send the report to, reusing the recipient already saved with that email (or the name of the user with that email) when there is one. Required when `recipient_email` isn't sent.
`recipient_email`	string	When `old_recipient_email` is missing	Email of a new recipient. Required when `old_recipient_email` isn't sent.
`recipient_first_name`	string	When `old_recipient_email` is missing	The new recipient's first name. Max 100 characters. Required when `old_recipient_email` isn't sent.
`recipient_last_name`	string	When `old_recipient_email` is missing	The new recipient's last name. Max 100 characters. Required when `old_recipient_email` isn't sent.

recipient_email and old_recipient_email must be real addresses on a domain that receives mail (they're checked with an RFC + DNS lookup), so addresses like @example.com are rejected with 422.

Request payload

{
  "reportType": "activity_report",
  "reportPeriodType": "month",
  "all_store": 0,
  "store_ids": [
    3007
  ],
  "recipient_email": "<recipient-email>",
  "recipient_first_name": "Jane",
  "recipient_last_name": "Smith"
}

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`response`	string	The confirmation message, `Report has been saved successfully!`.

The response doesn't return the new report's id. You need report_id to edit or delete the report later: get it from List scheduled reports (POST /api/v1/email-report/list) and match on the recipient email and report type.

Response payload

{
  "data": {
    "status": "success",
    "response": "Report has been saved successfully!"
  }
}

Examples

Success payload

See Response payload.

Error payload

403 Not an Account token

{
  "message": "This action is unauthorized."
}

422 Required fields missing

{
  "message": "The old recipient email field is required when recipient email is not present. (and 6 more errors)",
  "errors": {
    "old_recipient_email": [
      "The old recipient email field is required when recipient email is not present."
    ],
    "recipient_email": [
      "The recipient email field is required when old recipient email is not present."
    ],
    "recipient_first_name": [
      "The recipient first name field is required when old recipient email is not present."
    ],
    "recipient_last_name": [
      "The recipient last name field is required when old recipient email is not present."
    ],
    "reportType": [
      "The report type field is required."
    ],
    "reportPeriodType": [
      "The report period type field is required."
    ],
    "all_store": [
      "The all store field is required."
    ]
  }
}

422 Period doesn't fit the report type

An activity_report sent daily, to an address that fails the DNS check:

{
  "message": "The recipient email field must be a valid email address. (and 1 more error)",
  "errors": {
    "recipient_email": [
      "The recipient email field must be a valid email address."
    ],
    "reportPeriodType": [
      "The period type must be \"month\" when the report type is \"activity_report\"."
    ]
  }
}

422 Location outside your account

{
  "message": "The selected store_ids.0 does not belong to your company hierarchy.",
  "errors": {
    "store_ids.0": [
      "The selected store_ids.0 does not belong to your company hierarchy."
    ]
  }
}

Status	Meaning
`200`	The report is scheduled.
`401`	The token is missing, expired or invalid.
`403`	The token isn't an Account token (only account users can schedule this report).
`422`	A required field is missing, `reportPeriodType` doesn't fit `reportType`, a location is outside your account, or an email fails the RFC + DNS check.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/user/reports/add" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"reportType": "activity_report", "reportPeriodType": "month", "all_store": 0, "store_ids": [3007], "recipient_email": "<recipient-email>", "recipient_first_name": "Jane", "recipient_last_name": "Smith"}'