Customers Bulk Import
Uploading customer data via bulk import in a CSV file
Method Description
The examples in the documentation include sample POST requests. Keep in mind that these are just examples — your Maestra integration won’t work properly if they’re used without adjusting them to your specific setup.
The exact methods needed for your use case are typically defined by your Maestra Forward Deployed Marketer in a technical specification. If you don’t have that document please reach out to them for clarification.
Invoked with a POST request. Request address and input fields can be set up via Maestra framework.
POST https://api.maestra.io/v3/operations/bulk?endpointId={API endpoint ID}&operation=DirectCrm.Customers.Import&csvCodePage=65001&csvColumnDelimiter=%3B&csvTextQualifier=%22&segment={Customer segment system name}&SourceActionTemplate={Customer Sign-Up Action}&transactionId={Idempotency key value in GUID format}
Authorization: SecretKey {authorization key}
Accept: application/json
Content-Type: text/csv;charset=utf-8Request parameters
| Parameter | Description |
|---|---|
csvCodePage | Windows code page identifier for the CSV file. Use 65001 (UTF-8) whenever possible. |
csvColumnDelimiter | Character used to separate columns in the CSV file. |
csvTextQualifier | Optional character added at the start and end of a column value, allowing it to contain characters that would otherwise be restricted. |
endpointId | The integration endpoint to pull settings from. Configured in your Maestra account. |
segment | System name of the segment. |
SourceActionTemplate | The customer registration action — for example, Website registration or In-store paper form. Configured in your Maestra account.. |
transactionId | Idempotency key that prevents duplicate request execution. Must be a GUID (v4 recommended). Repeated requests with the same key will return TransactionAlreadyProcessed. |
Limits & supported formats
- Rate limit: No more than 60 imports per hour. Requests exceeding this limit will return
429 Too Many Requestsuntil the count drops below 60.- Max file size: 200 MB. If you need to import more data, split it across multiple files.
- gzip support: Supported. The server must return a
Content-Encoding: gzipheader, and the file must be attached in binary form (e.g., set tobinaryin Postman).
Field Descriptions
| Title | Description |
|---|---|
| Websiteid | Customer website ID |
| FirstName | Customer first name |
| LastName | Customer last name |
| MiddleName | Customer middle name |
| MobilePhone | Mobile phone |
| Customer email | |
| BirthDate | Date of birth as yyyy-MM-dd |
| SourceDateTime | Sign-up date and time as yyyy-MM-dd HH:mm:ss, project time |
| SourcePointOfContact | Sign-up point of contact, for example 'Site' or 'Boston Store' |
| IsSubscribed | Subscription status, true or false |
| Optional Customer Field | Optional customer field value |
For a full list of accepted fields, see here:
https://{your_project_name}.maestra.io/customers/import
Sample Request
POST https://api.maestra.io/v3/operations/bulk?endpointId=Maestra&operation=DirectCrm.Customers.Import&csvCodePage=65001&csvColumnDelimiter=%3B&csvTextQualifier=%22&SourceActionTemplate=CustomerCreatebyStaff&transactionId=f47ac10b-58cc-4372-a567-0e02b2c3d479
Authorization: SecretKey bWFuemFuuYTowcXY3ODMuzNjI2M3EzT0Y
Accept: application/json
Content-Type: text/csv;charset=utf-8
Email;balance;BirthDate;SourceDateTime;Region;SourcePointOfContact;LastName;FirstName;MiddleName;IsSubscribed
[email protected];433;12.04.1982;16.04.2016 21:00;711;727;Smith;Mary;Ann;1
[email protected];324;16.01.1980;16.04.2016 21:00;714;727;Smith;John;Michael;1Updated 16 days ago