Send review-site connection-request invite

Overview

Emails a tokenized review-site connection invite for a store and echoes the connect URL + token so the UI can also show copy/resend. The response reflects the real dispatch outcome (sent / queued / skipped / failed).

Prerequisites

• A bearer token. Callable with Partner and Account tokens.

Base URL

Endpoint

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

Authentication

• Requires a bearer token in the Authorization: Bearer <bearer-token> header.

• Who can call it: Partner and Account tokens.

• The store is targeted by store_id OR client_location_id (resolved to a store id scoped to the caller's company). Both pass an ownership check, so the store must be in the auth user's hierarchy.

• A Partner can invite for any store under its tree. An Account only for its own account's stores.

Rate limit

• No rate limit.

Request body

• Body:

{
  "store_id": 10,
  "email": "[email protected]",
  "name": "Jane Doe"
}

Response

• data.status (string) — always success on the happy path.
• data.delivered (bool) — true when delivery status is sent or pending(queued).
• data.delivery_status (string) — sent | pending | skipped | failed.
• data.skip_reason (string|null) — e.g. template disabled / recipient suppressed.
• data.message (string) — human summary matching the delivery status.
• data.connect_url (string) — the store's connect-review-sites URL.
• data.token (string) — raw hashid of [store_id, 15] for copy/resend.
• data.recipient (string) — echoed email.

200 Success · 200

{
  "data": {
    "status": "success",
    "delivered": true,
    "delivery_status": "sent",
    "skip_reason": null,
    "message": "Invitation email sent successfully.",
    "connect_url": "https://app.example.com/connect-review-sites/<invite-token>",
    "token": "<invite-token>",
    "recipient": "[email protected]"
  }
}

422 Out-of-scope store_id · 422

{
  "message": "The store ID is invalid for the authenticated user.",
  "errors": {
    "store_id": [
      "The store ID is invalid for the authenticated user."
    ]
  }
}

422 Email fails DNS-MX lookup · 422

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

Errors

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": 10, "email": "[email protected]", "name": "Jane Doe"}'