Upload audience

Overview

Upload an Excel/CSV audience file to a draft bulk-upload campaign. The API stores the file on S3 and dispatches an async job (ProcessCampaignAudienceUpload) to parse and validate recipients.

Prerequisites

• A bearer token. Callable with Partner and Account tokens.
• The campaignId of the record you are targeting.

Base URL

Endpoint

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

Authentication

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

• Who can call it: Partner and Account tokens.

• The endpoint scopes the campaign in-controller. This matches the caller's person.company_id against the campaign-store's company or its parent/grandparent.

• Any Partner- or Account-tier user within the campaign's company tree may upload.

• Rejected (400) unless status === 'draft' and type is neither automation nor kiosk.

Rate limit

• No rate limit.

Path parameters

Request body

• Body (multipart/form-data):

Response

• data.message (string) — "File uploaded successfully. Processing will begin shortly."
• data.campaign_id (integer) — the campaign ID.
• data.file_name (string) — original uploaded filename.

Note: on accept, the campaign row is updated (request_file_path, request_file_name, request_file_status='processing', type='bulk_upload', counters reset) before the job is queued; actual parsing happens asynchronously.

200 Success · 200

{
  "data": {
    "message": "File uploaded successfully. Processing will begin shortly.",
    "campaign_id": 1,
    "file_name": "audience.xlsx"
  }
}

Errors

Example request

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