Upload recipients

Overview

Add customers to a campaign from a spreadsheet.

Use this to load a campaign's recipient list before launching.

You'll need the campaign's id (in the path) and a CSV or Excel file with the required columns.

The file is checked and stored straight away, then processed in the background. Follow progress, and see which rows were added or skipped, with List recipients.

It accepts a draft campaign whose type is unset or already bulk_upload, and sets the type to bulk_upload. It won't switch a kiosk or automation campaign to bulk_upload.

Prerequisites

• A bearer token. See Authentication.
• A draft campaign (campaignId) whose type is unset or bulk_upload.
• A .csv, .xlsx or .xls file, up to 10 MB, with an Email or Cell Phone column.

Base URL

Endpoint

POST /api/v1/campaign/{campaignId}/upload-audience

Authentication

Partner or Account token

• The campaign's location must be inside your own account tree. If it isn't, or the campaign has no location, the call returns 403 (Unauthorized access to campaign.).

Rate limit

This endpoint has no rate limit.

Request parameters

Request body

Sent as multipart/form-data.

Request payload

One file field, file. For example, a CSV:

Customer Name,Email,Cell Phone
Jane Smith,<customer-email>,+15555550100

Response body

The payload is inside data.

Response payload

{
  "data": {
    "message": "File uploaded successfully. Processing will begin shortly.",
    "campaign_id": 4824,
    "file_name": "recipients.csv"
  }
}

Examples

Success payload

See Response payload.

Error payload

400 Campaign is kiosk or automation

{
  "message": "Bad Request",
  "status": "error",
  "errors": {
    "message": "Only bulk upload campaigns can be updated via this endpoint."
  }
}

400 Campaign already launched

{
  "message": "Bad Request",
  "status": "error",
  "errors": {
    "message": "Campaign is finalised and cannot be updated."
  }
}

400 Header row invalid

Also Invalid file format. The file appears to be empty or corrupted. and Unable to read file headers. Please ensure the file is a valid Excel or CSV format.

{
  "message": "Bad Request",
  "status": "error",
  "errors": {
    "file": [
      "Either \"Email\" or \"Cell Phone\" column is required"
    ]
  }
}

403 Campaign outside your account

{
  "message": "Unauthorized access to campaign.",
  "status": "error",
  "errors": []
}

404 Campaign not found

{
  "message": "Campaign not found",
  "status": "error",
  "errors": []
}

422 File missing

{
  "message": "Please select a file to upload.",
  "errors": {
    "file": [
      "Please select a file to upload."
    ]
  }
}

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/campaign/4824/upload-audience" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --form '[email protected]'