Import a customer base

You are launching your programme with an existing base: a Salesforce or HubSpot export, or a plain CSV file. Do not create customers one by one: import them in bulk.

Two paths

	CSV import	Bulk create (JSON)
Endpoint	POST/csv-operations/import-csv	POST/clients/bulk
Format	CSV file as multipart/form-data	items array as application/json
Best for	A one-off migration from an export	A recurring sync from your CRM
Tracking	GET/csv-operations	GET/bulk-operations/{operationId} or webhookUrl

Before you start

• The loyalty card is configured (PATCH/store-cards). See Templates and passes.
• Customer types exist if you segment your base.
• A valid API token. See Authentication.

Step 1 · Prepare the file

One row per customer. Useful columns: first name, last name, email (required), phone, and if you have them: barcode (your customer number), customer type, starting balance, birth date, renewal date, admission date, company.

Rule	Why
One unique email per customer	An email already in the wallet is rejected (EMAIL_ALREADY_EXISTS).
One unique barcode	Two customers never share a barcode (BARCODE_ALREADY_EXISTS).
Phone in international format (+33…)	Required for SMS.
UTF-8 encoding	Accented names stay readable on the card.

For the exact file template (column names, separator), contact eldo wallet support.

Step 2 · Upload the file

POST/csv-operations/import-csvTry it →

• curl
• SDK Node.js
• nodejs
• php
• python
• java
• csharp
• go
• ruby

• CURL

curl -L 'https://api-v2.test.eldowallet.fr/csv-operations/import-csv' \
-H 'Accept: application/json' \
-H 'x-lang: en' \
-H 'Authorization: Bearer <token>' \
-F 'file=@"clients.csv"' \
-F 'sendNotificationsToCustomers="false"'

Let curl write the Content-Type

With -F, curl sends multipart/form-data with its boundary. Do not add a Content-Type header yourself.

The import runs in the background. Track it with GET/csv-operations.

Step 3 · Decide who sends the cards

sendNotificationsToCustomers decides what happens after the import:

Value	What happens	Best for
"true"	eldo wallet sends each customer their add-to-Wallet link.	A launch with immediate activation.
"false"	Records are created, nobody is notified.	A silent migration, then your own campaign when you choose.

On the JSON path (POST/clients/bulk), make the same choice per customer with sendCard.

Alternative · Bulk create in JSON

POST/clients/bulkTry it →

• curl
• SDK Node.js
• nodejs
• php
• python
• java
• csharp
• go
• ruby

• CURL

curl -L 'https://api-v2.test.eldowallet.fr/clients/bulk' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'x-lang: en' \
-H 'Authorization: Bearer <token>' \
--data-raw '{
  "webhookUrl": "https://crm.example.com/hooks/eldo",
  "items": [
    {
      "firstName": "Marie",
      "lastName": "Durand",
      "email": "marie@example.com",
      "source": "CRM",
      "sendCard": true
    },
    {
      "firstName": "Loïc",
      "lastName": "Martin",
      "email": "loic@example.com",
      "barcode": "CRM-000124",
      "source": "CRM",
      "sendCard": true
    }
  ]
}'

• Up to 5,000 items per call, processed asynchronously.
• The response holds the operation id: track it with GET/bulk-operations/{operationId}, or wait for the call on webhookUrl.
• forceSync: true forces synchronous processing, rejected from 1,000 items (SYNC_EXECUTION_NOT_ALLOWED).

Step 4 · Handle rejects

Check the operation result: customers created, duplicates, invalid rows. Fix the rejected rows and resend only those. Resending the whole file produces duplicate errors.

Step 5 · Track activation

• GET/clients/stats: number of customers and installed cards.
• GET/clients: paginated, filterable list (status, createdAtStart, search…).
• POST/clients/reminder-inactive: nudge those who have not installed their card.
• Webhooks: get pass.installed when a customer adds their card.

Maximum volume

A wallet holds up to 100,000 customers (SYSTEM_DOES_NOT_SUPPORT_MORE_THAN_100000_CUSTOMERS).

Go further

• Retail use case
• Email or SMS not received
• Common API errors