Edit a file format

Overview

Change a campaign's column mapping.

Use this when your export format changes.

You'll need the mapping id and the changes. Send only the fields you want to change.

Returns the updated mapping. A new sample file replaces the old one.

Prerequisites

A bearer token. See Authentication.
The file format's id (fileHeaderId).

Base URL

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

Endpoint

PUT /api/v1/campaign/automate/file-headers/{fileHeaderId}

Authentication

Account token

The file format's campaign must be an automation campaign in your own account; otherwise 403.

Rate limit

This endpoint has no rate limit.

Request parameters

Parameter	In	Type	Required	Description
`fileHeaderId`	path	integer	Yes	The file format id. Digits only.

Request body

Sent as multipart/form-data. Every field is optional.

Field	Type	Required	Description
`headers`	string (JSON object)	No	A new column mapping, as a JSON object. When sent, it must have non-empty string values for `email`, `phone`, `customer_name` and `location_identifier`; otherwise `400`.
`sample_file`	file	No	A new sample file: `.xlsx`, `.xls` or `.csv`, up to 10 MB. Replaces the old one.
`location_identifier`	string	No	A new value for the location column that marks this campaign's rows, up to 255 characters.

Request payload

Form fields (any of them):

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 updated successfully`.
`data`	object	The updated 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 updated successfully",
    "data": {
      "id": 4,
      "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",
      "created_at": "2026-10-01T10:30:00.000000Z",
      "updated_at": "2026-10-02T09:00:00.000000Z",
      "sample_file_url": "https://d2ny6zb7otrnhl.cloudfront.net/campaign_automation/sample_files/1718447400_sample.xlsx"
    }
  }
}

Examples

Success payload

See Response payload.

Error payload

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": {
    "headers": [
      "Headers must contain all required keys: Location identifier field mapping"
    ]
  }
}

403 Not your file format

{
  "message": "Not authorized to update this file header configuration",
  "status": "error",
  "errors": []
}

404 File format not found

{
  "message": "File header configuration not found",
  "status": "error",
  "errors": []
}

422 Invalid field

{
  "message": "The headers field must be a valid JSON string.",
  "errors": {
    "headers": [
      "The headers field must be a valid JSON string."
    ]
  }
}

Status	Meaning
`200`	The updated file format.
`400`	`headers` is missing a key or has an empty value.
`401`	The token is missing, expired or invalid.
`403`	The file format's campaign isn't an `automation` campaign in your account.
`404`	No file format has that id.
`422`	`headers` isn't valid JSON, the sample file is too large or not xlsx, xls or csv, or `location_identifier` is too long.
`500`	Unexpected server error.

Example request

curl --request PUT \
  --url "https://production-api.shoutaboutus.com/api/v1/campaign/automate/file-headers/4" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --form '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'