Create file headers

Overview

Create the file-header (column-mapping) configuration for an automation campaign and upload the sample file to S3. The endpoint deletes any existing file-header for the campaign first, and the campaign's type is forced to automation. Sent as multipart/form-data. Emits an audit event (CAMPAIGN_FILE_HEADERS_CREATED).

Prerequisites

A bearer token in the Authorization header.

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

Requires a bearer token in the Authorization: Bearer <bearer-token> header.
Account bearer. The campaign must belong to the caller's person.company_id, else 404.

Rate limit

No rate limit.

Request body

Field	Type	Required	Description
`rs_campaign_id`	integer	Required	Must be an existing campaign and must be owned by caller and not bulk_upload/kiosk.
`file_headers`	string (JSON)	Required	JSON object; must contain non-empty string values for `email`, `phone`, `customer_name`, `location_identifier`.
`sample_file`	file	Required	`mimes:xlsx,xls,csv`, max 10 MB (10240 KB).
`location_identifier`	string	Required	Max 255. Unique per campaign store-group.

How it works

201 with the created CampaignAutomationFileHeader row under data.data.
400 if the campaign is a bulk_upload/kiosk type, or file_headers is missing required keys / has non-string values.
404 if the campaign is not found or not owned by the caller.
422 if base validation fails (missing file, wrong mime, duplicate location_identifier, etc.).

Saves data.data.id into fileHeaderId for the update/delete/sample-file requests.

Response

201 Created · `201`

{
  "data": {
    "status": "success",
    "message": "File headers created successfully",
    "data": {
      "rs_campaign_id": 12,
      "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": "Store ID",
      "updated_at": "2026-06-15T10:30:00.000000Z",
      "created_at": "2026-06-15T10:30:00.000000Z",
      "id": 4
    }
  }
}

400 Invalid campaign type · `400`

{
  "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."
    ]
  }
}

404 Campaign not found · `404`

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

422 Validation error · `422`

{
  "message": "The sample file field is required.",
  "errors": {
    "sample_file": [
      "The sample file field is required."
    ]
  }
}

Errors

Status	Meaning
`400`	Invalid campaign type
`401`	The bearer token is missing, expired or invalid
`404`	Campaign not found
`422`	Validation error
`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=123' \
  --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=Store ID'

Updated 11 days ago

Did this page help you?