Define a file format

Overview

Tell a campaign which columns in your file mean what: name, email, phone, and the column that identifies the location.

Use this once per file format before your first automated upload.

You'll need the campaign_id and the column mapping.

Returns the mapping with its id. It replaces any file format the campaign already had, and makes the campaign an automation campaign. A bulk_upload or kiosk campaign is refused with 400.

Prerequisites

A bearer token. See Authentication.
A campaign in your account (rs_campaign_id) whose type is unset or automation.
A sample file (.xlsx, .xls or .csv, up to 10 MB) in the format you will upload.

Base URL

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

Endpoint

POST /api/v1/campaign/automate/file-headers

Authentication

Account token

The campaign must belong to your own account; otherwise 404 (Campaign not found or not authorized).

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Sent as multipart/form-data.

Field	Type	Required	Description
`rs_campaign_id`	integer	Yes	The campaign. Must exist (otherwise `422`), belong to your own account (otherwise `404`), and not be `bulk_upload` or `kiosk` (otherwise `400`).
`file_headers`	string (JSON object)	Yes	A JSON object mapping each field to a column name in your file. Must have non-empty string values for `email`, `phone`, `customer_name` and `location_identifier`; otherwise `400`.
`sample_file`	file	Yes	A sample file in your format: `.xlsx`, `.xls` or `.csv`, up to 10 MB.
`location_identifier`	string	Yes	The value in your location column (the one named by `file_headers.location_identifier`) that marks this campaign's rows; other rows are skipped. Up to 255 characters. Must not already be used by a file format at another location.

Request payload

Form fields:

rs_campaign_id=4827
file_headers={"email":"Email Address","phone":"Phone Number","customer_name":"Customer Name","location_identifier":"Store ID"}
sample_file=@sample_file.xlsx
location_identifier=loc-00123

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`message`	string	`File headers created successfully`.
`data`	object	The new file format.
`data.id`	integer	The file format's id (`fileHeaderId`).
`data.rs_campaign_id`	integer	The campaign it belongs to.
`data.headers`	object	Which column in your file holds each field: `email`, `phone`, `customer_name` and `location_identifier` map to column names.
`data.sample_file_path`	string	Storage path of the sample file.
`data.location_identifier`	string	The value in the location column that marks this campaign's rows.
`data.created_at`	string	When the file format was created.
`data.updated_at`	string	When it last changed.
`data.sample_file_url`	string	URL of the sample file.

Response payload

{
  "data": {
    "status": "success",
    "message": "File headers created successfully",
    "data": {
      "rs_campaign_id": 4827,
      "headers": {
        "email": "Email Address",
        "phone": "Phone Number",
        "customer_name": "Customer Name",
        "location_identifier": "Store ID"
      },
      "sample_file_path": "campaign_automation/sample_files/1718447400_sample.xlsx",
      "location_identifier": "loc-00123",
      "updated_at": "2026-10-01T10:30:00.000000Z",
      "created_at": "2026-10-01T10:30:00.000000Z",
      "id": 4,
      "sample_file_url": "https://d2ny6zb7otrnhl.cloudfront.net/campaign_automation/sample_files/1718447400_sample.xlsx"
    }
  }
}

Examples

Success payload

See Response payload.

Error payload

400 Campaign is bulk upload or kiosk

{
  "message": "Bad Request",
  "status": "error",
  "errors": {
    "rs_campaign_id": [
      "This campaign is a bulk upload campaign. You can't create file header configuration for a bulk upload campaign or kiosk campaign."
    ]
  }
}

400 Mapping missing a key

Also Headers must be a non-empty object and Value for 'email' must be a non-empty string.

{
  "message": "Bad Request",
  "status": "error",
  "errors": {
    "file_headers": [
      "Headers must contain all required keys: Location identifier field mapping"
    ]
  }
}

404 Campaign not found

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

422 Fields missing

{
  "message": "The rs campaign id field is required. (and 3 more errors)",
  "errors": {
    "rs_campaign_id": [
      "The rs campaign id field is required."
    ],
    "file_headers": [
      "The file headers field is required."
    ],
    "sample_file": [
      "The sample file field is required."
    ],
    "location_identifier": [
      "The location identifier field is required."
    ]
  }
}

Status	Meaning
`201`	The file format is saved; the campaign is now `automation`.
`400`	The campaign is `bulk_upload` or `kiosk`, or `file_headers` is missing a key or has an empty value.
`401`	The token is missing, expired or invalid.
`404`	The campaign isn't in your account.
`422`	A field is missing or invalid, the sample file is too large or not xlsx, xls or csv, or `location_identifier` is used at another location.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/campaign/automate/file-headers" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --form 'rs_campaign_id=4827' \
  --form 'file_headers={"email":"Email Address","phone":"Phone Number","customer_name":"Customer Name","location_identifier":"Store ID"}' \
  --form 'sample_file=@sample_file.xlsx' \
  --form 'location_identifier=loc-00123'