CustomersCreate Bulk Customer

Create Bulk Customer

Use this endpoint to create several customers in one request. It is useful when onboarding many customers or preparing a group of customers for bulk virtual-account creation.

The response includes a batchid. Save it because you will need it when calling Create Bulk Virtual Account.

This request uses your secret key and must be made from a secure backend server. Never expose your secret key in browser or mobile-app code.

API Endpoint

POST https://backendapi.sayswitchgroup.com/api/v1/customer/bulk_create

Request Body

{
  "customers": [
    {
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "08012345678",
      "bvn": "22358970815"
    },
    {
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Smith",
      "phone": "08087654321"
    }
  ]
}

Replace the sample customer details with values collected from your own application.

FieldTypeRequiredDescription
customersarrayYesThe customers to create.
customers[].emailstringYesThe customer’s valid email address.
customers[].first_namestringYesThe customer’s first name.
customers[].last_namestringYesThe customer’s last name.
customers[].phonestringYesThe customer’s phone number.
customers[].bvnstringNoThe customer’s Bank Verification Number, when required. Only collect and send it with the customer’s consent and appropriate security controls.

Sample Request

curl -X POST https://backendapi.sayswitchgroup.com/api/v1/customer/bulk_create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -d '{
    "customers": [
      {
        "email": "john@example.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "08012345678",
        "bvn": "22358970815"
      },
      {
        "email": "jane@example.com",
        "first_name": "Jane",
        "last_name": "Smith",
        "phone": "08087654321"
      }
    ]
  }'

Success Response

{
  "status": true,
  "message": "Customers processed",
  "data": {
    "batchid": "0705855c54999",
    "totalSubmitted": 2,
    "totalCreated": 2,
    "totalSkipped": 0,
    "domain": "live"
  }
}
FieldTypeDescription
statusbooleanIndicates whether the request was processed successfully.
messagestringA summary of the result.
data.batchidstringThe batch identifier used for bulk virtual-account creation.
data.totalSubmittedintegerNumber of customers submitted.
data.totalCreatedintegerNumber of customers created.
data.totalSkippedintegerNumber of customers skipped, for example because they already exist.
data.domainstringThe environment in which the customers were processed.

The response field is batchid, while the next request expects batchId. Use the exact spelling shown for each endpoint.

Validation Errors

If a customer record is incomplete or invalid, the API returns a non-success HTTP status with a message describing the problem. Check both the HTTP status and response body, correct the affected customer data, and then submit the request again. Do not assume that every submitted customer was created; compare totalSubmitted, totalCreated, and totalSkipped.

Next Step

Pass the returned data.batchid to Create Bulk Virtual Account as batchId.