Schedule a partner email report

Overview

Set up a recurring email report for your team: what to include, how often, who gets it.

Use this so your ops team gets a digest without logging in.

You'll need the schedule, recipients, and report options.

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

Prerequisites

A Partner bearer token. See Authentication.
The report type and how often to send it, the accounts to cover, and the recipient: an existing user's 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/partner/reports/add

Authentication

Partner token

Only Partner tokens can call it. Any other token gets 403 (This action is unauthorized.).
The report belongs to your partner. Each id in account must be an account inside your own tree; anything else is rejected with 422.
The recipient is either an existing user (old_recipient_email) or a new recipient created from recipient_email and the name.

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_account`	integer	Yes	`1` to cover every account under your partner, `0` to cover only the accounts in `account`.
`account`	array of integers	When `all_account` is `0`	Account ids to cover. Required when `all_account` is `0`. Each must exist and be inside your tree.
`old_recipient_email`	string	When `recipient_email` is missing	Email of an existing user to send the report to. Required when `recipient_email` isn't sent. No user with that email returns `400`.
`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_account": 0,
  "account": [
    5994
  ],
  "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

400 User not found

No user has the old_recipient_email you sent:

{
  "message": "Bad Request",
  "status": "error",
  "errors": {
    "status": "error",
    "response": "User not found!"
  }
}

403 Not a Partner token

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

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\"."
    ]
  }
}

Status	Meaning
`200`	The report is scheduled.
`400`	No user has that `old_recipient_email` (`User not found!`), or the user behind the token has no company (`Company not found!`).
`401`	The token is missing, expired or invalid.
`403`	The token isn't a Partner token.
`422`	A required field is missing, `reportPeriodType` doesn't fit `reportType`, an account is outside your tree, 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/partner/reports/add" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"reportType": "activity_report", "reportPeriodType": "month", "all_account": 0, "account": [5994], "recipient_email": "<recipient-email>", "recipient_first_name": "Jane", "recipient_last_name": "Smith"}'