Upload locations for review

Overview

Upload a spreadsheet of new locations for an account. Our team checks it and creates the locations once verified.

Use this to add many locations to an existing account. Because it goes through a verification step, it's not instant; expect the locations to appear within a business day or two.

You'll need the account_id and a spreadsheet in the template format.

The file is validated row by row and accepted; you'll get an error naming any row that fails. Our team is notified to verify and create the locations. You're not charged until they exist.

Prerequisites

• A Partner or Account token. See Authentication.
• The account's id (account_id).
• A spreadsheet made from the template. See Download the locations spreadsheet template.

Base URL

Endpoint

POST /api/v1/bulk-upload/locations

Authentication

Partner or Account token

• account_id must be an existing, not deleted account inside your own account tree; otherwise 422.
• A Partner token can upload for any account under the partner; an Account token only for its own account.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Send the body as multipart/form-data.

Start from the template (Download the locations spreadsheet template). The header row must have exactly these 13 columns, in this order: Location Name, store_id, Website, Address, City, State, Zip, Country Code, Business Phone, Location User First Name (optional), Location User Last Name (optional), Location User Email Address (optional), Location User Phone number (optional). Headers are compared after lower-casing and replacing spaces and brackets with underscores (location_name, location_user_first_name_optional, …), so the order matters; columns after the 13th are ignored. store_id and Website are accepted but not validated.

Each row is checked: address, city, state, zip, business_phone (9 to 10 characters, no formatting), country_code (must be a known country code) and location_name are required. location_user_phone_number_optional and location_user_email_address_optional (a deliverable email that doesn't already belong to a user and isn't repeated in the file) are optional. Formula values (#NAME?) are rejected.

Request payload

Form fields:

account_id=5994
location_file=@location_file.xlsx

Response body

The payload is inside data. Row errors also come back as 200, with status error.

Response payload

{
  "data": {
    "status": "success",
    "message": "Thank you. Upload complete. We will confirm with you once data and locations are live."
  }
}

Examples

Success payload

Rows that failed the checks (nothing is uploaded; fix the rows and upload again):

{
  "data": {
    "message": "Please correct the errors and re-upload the file.",
    "status": "error",
    "errors": {
      "3": [
        "The address field is required.",
        "Country code must be a valid country code."
      ],
      "5": [
        "The Business phone field is required. Do not enter ( ) or - in the phone number field Please only enter the 10 digit numbers with no country code."
      ]
    }
  }
}

Error payload

400 Header doesn't match the template

{
  "message": "Bad Request",
  "status": "error",
  "errors": {
    "location_file": "The Excel file is invalid. The header names and order must match those in the template file."
  }
}

400 Empty file

{
  "message": "Bad Request",
  "status": "error",
  "errors": {
    "location_file": "The uploaded file appears to be empty."
  }
}

422 Fields missing

{
  "message": "The account id field is required. (and 1 more error)",
  "errors": {
    "account_id": ["The account id field is required."],
    "location_file": ["The location file field is required."]
  }
}

422 Wrong account or file type

{
  "message": "The account is invalid or deleted. (and 1 more error)",
  "errors": {
    "account_id": ["The account is invalid or deleted."],
    "location_file": ["The location file field must be a file of type Excel"]
  }
}

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/bulk-upload/locations" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --form 'account_id=5994' \
  --form 'location_file=@location_file.xlsx'