Create customer

POST

/customers

curl --request POST \
  --url https://api.pipevest.com/v1/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: <x-client-id>' \
  --data '{ "firstName": "John", "lastName": "Doe", "msisdn": "260971234567", "isActive": true, "identificationNumber": "example", "identificationType": "SSN", "referenceId": "example" }'

• Production
• Sandbox (UAT)

Authorizations

• bearerAuth
• clientId

Parameters

Header Parameters

X-Idempotency-Key

string format: uuid

Idempotency key (UUID) for safely retrying mutating requests. Enforcement is being rolled out during onboarding.

Request Body^required

Media typeapplication/json

object

firstName

required

string

<= 100 characters

Example

John

lastName

required

string

<= 100 characters

Example

Doe

msisdn

7–15 digit mobile number.

string

/^\d{7,15}$/

Example

260971234567

isActive

boolean

default: true

identificationNumber

string

<= 50 characters

identificationType

string

Allowed values: SSN PASSPORT DRIVER_LICENSE NATIONAL_ID TAX_ID OTHER

referenceId

Your own external reference for this customer.

string

<= 100 characters

Responses

201

Customer created

Media typeapplication/json

object

message

string

data

object

id

string

organizationId

string

firstName

string

lastName

string

msisdn

string

nullable

isActive

boolean

identificationNumber

string

nullable

identificationType

string

Allowed values: SSN PASSPORT DRIVER_LICENSE NATIONAL_ID TAX_ID OTHER

referenceId

string

nullable

createdAt

string format: date-time

updatedAt

string format: date-time

Example

{
  "message": "Customer created successfully",
  "data": {
    "id": "clx0a1b2c3d4e5f6g7h8i9j0k",
    "organizationId": "clorgb2c3d4e5f6g7h8i9j0k1",
    "firstName": "John",
    "lastName": "Doe",
    "msisdn": "260971234567",
    "isActive": true,
    "identificationType": "SSN"
  }
}

400

Request failed schema validation

Media typeapplication/json

object

error

string

details

Array<object>

object

field

string

message

string

Example

{
  "error": "Validation failed",
  "details": [
    {
      "field": "firstName",
      "message": "First name is required"
    }
  ]
}

401

Authentication failed

Media typeapplication/json

object

error

string

message

string

Example

{
  "error": "Unauthorized",
  "message": "Invalid organization authentication token"
}