Create import batch

Registers a new customer import or update batch and returns a pre-signed S3 URL that the data file should be uploaded to.

The bulk workflow is:

  1. Call this endpoint with the batch name, file name, and mode. The response carries the batchId and signedUrl.
  2. PUT the CSV or XLSX file to signedUrl. Uploading the file is what triggers processing, so the batch remains pending until the file arrives.
  3. Poll Get import batch until status is completed, completed_with_errors, or failed.
  4. If the batch completed with errors, fetch the annotated error file with Get import error file, then correct and resubmit those rows using Retry import batch.

File constraints: the file must be a .csv or .xlsx file, may not exceed 10 MB, and the file name may not contain a forward slash ( / ), backslash ( ** ), or double period ( .. ).

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

The payload used to register a new customer import or update batch.

string
required

The label you want assigned to this batch.

string
required

The name of the file you will upload to the returned signedUrl. The file name must end in .csv or .xlsx and may not contain a forward slash ( / ), backslash ( ** ), or double period ( .. ).

string
enum
Defaults to import

The type of batch.

  • import-Create new customers, applying full required-field validation to every row (Default)
  • update-Update existing customers, matching rows by their ID columns and validating only the columns present in the file

Any other value is treated as import.

Allowed:
integer

The ID of the user submitting this batch. This value is recorded as the batch creator.

integer

Ignored. The client is derived from the API key used for the request.

Responses

Language
Credentials
Header
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json