Send the business owner a connection link

Overview

Email the business owner a link to your branded connection page, where they authorize response posting for the location's sites: sign in to Google or Facebook, or follow the manager-invite steps for Yelp and similar. The link is also returned to you, so you can show it in your own app or resend it.

Use this when you want to respond to a location's reviews. The owner has to grant access themselves; this is how they do it. One invite covers every site on the location.

You'll need the store_id or client_location_id, the owner's email, and optionally their name.

Returns whether the email was sent, queued, skipped, or failed, plus the connect_url and token so you can deliver the link your own way. When the owner finishes, posting status on each site they authorized changes to connected. If a connection later breaks (password change, expired access), send this again; the same page shows a Fix option.

Prerequisites

A bearer token. See Authentication.
The location's store_id, or your own client_location_id for it.
The owner's email address.

Base URL

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

Endpoint

POST /api/v1/store-review-site/send/request

Authentication

Partner or Account token

The location must be inside your own account tree. A Partner token can invite for any location under the partner; an Account token only for its own account's locations.
A location outside your tree is rejected with 422.

Rate limit

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

Request parameters

None.

Request body

Field	Type	Required	Description
`store_id`	integer	No	The location. Required unless you send `client_location_id`. Must exist and be inside your account tree.
`client_location_id`	string	No	Your own id for the location, used instead of `store_id`. Up to 255 characters.
`email`	string	Yes	Who receives the invite. Must be a valid address on a domain that accepts mail (it's checked with a DNS lookup), so test domains like `example.com` are rejected with `422`.
`name`	string	No	The recipient's name, shown in the email. Up to 120 characters; no `<` or `>`.

Request payload

{
  "store_id": 3007,
  "email": "<owner-email>",
  "name": "Jane Smith"
}

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`, also when the email wasn't sent; check `delivery_status`.
`delivered`	boolean	`true` when the email was sent or queued (`delivery_status` `sent` or `pending`).
`delivery_status`	string	`sent`, `pending` (queued for delivery to your email webhook), `skipped` or `failed`.
`skip_reason`	string or null	Why it was skipped: `template_disabled` (the Review Site Connection Invite template is turned off) or `suppressed` (the recipient unsubscribed or is on the suppression list). Otherwise `null`.
`message`	string	A summary of the outcome, e.g. `Invitation email sent successfully.`
`connect_url`	string	The link to the location's connection page, on your white-label domain when you have one.
`token`	string	The invite hash in the link. Send it as `hash` to the connection endpoints instead of a token.
`recipient`	string	The email you sent.

Response payload

{
  "data": {
    "status": "success",
    "delivered": true,
    "delivery_status": "sent",
    "skip_reason": null,
    "message": "Invitation email sent successfully.",
    "connect_url": "https://production.shoutaboutus.com/connect-review-sites/5oogfx",
    "token": "5oogfx",
    "recipient": "<owner-email>"
  }
}

Examples

Success payload

Sent: see Response payload.

The template is turned off, so nothing was sent:

{
  "data": {
    "status": "success",
    "delivered": false,
    "delivery_status": "skipped",
    "skip_reason": "template_disabled",
    "message": "The Review Site Connection Invite template is turned off, so no invitation was sent.",
    "connect_url": "https://production.shoutaboutus.com/connect-review-sites/5oogfx",
    "token": "5oogfx",
    "recipient": "<owner-email>"
  }
}

Error payload

422 Missing fields

{
  "message": "The store id field is required when client location id is not present. (and 1 more error)",
  "errors": {
    "store_id": [
      "The store id field is required when client location id is not present."
    ],
    "email": [
      "The email field is required."
    ]
  }
}

422 Location outside your tree

{
  "message": "The selected store id does not belong to your company hierarchy.",
  "errors": {
    "store_id": [
      "The selected store id does not belong to your company hierarchy."
    ]
  }
}

422 Email fails the check

{
  "message": "The email field must be a valid email address.",
  "errors": {
    "email": [
      "The email field must be a valid email address."
    ]
  }
}

429 Too many requests

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

Status	Meaning
`200`	The outcome of the invite; check `delivery_status`.
`401`	The token is missing, expired or invalid.
`422`	No location sent, the location is outside your tree, or `email` or `name` is invalid.
`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/store-review-site/send/request" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"store_id": 3007, "email": "<owner-email>", "name": "Jane Smith"}'