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-Idempotency-Key: 2489E9AD-2EE2-8E00-8EC9-32D5F69181C0' \
  --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

required

string format: uuid

Idempotency key (UUID) scoped to your credential. Mandatory on this endpoint in Sandbox (UAT) and Production alike — a request without one is rejected with 400 "X-Idempotency-Key header is required for this request". Retrying with the same key replays the stored response verbatim rather than re-running the operation.

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, or the mandatory X-Idempotency-Key header is missing.

Media typeapplication/json

One of:

object

object

error

string

details

Array<object>

object

field

string

message

string

object

object

error

string

message

string

Examples

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

{
  "error": "Bad Request",
  "message": "X-Idempotency-Key header is required for this request"
}

401

Authentication failed

Media typeapplication/json

object

error

string

message

string

Example

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

409

A request with this X-Idempotency-Key is still in progress

Media typeapplication/json

object

error

string

message

string

Example

{
  "error": "Conflict",
  "message": "A request with this X-Idempotency-Key is already in progress"
}

422

The X-Idempotency-Key was already used with a different body

Media typeapplication/json

object

error

string

message

string

Example

{
  "error": "Unprocessable Entity",
  "message": "X-Idempotency-Key was already used with a different request payload"
}

429

Rate limit exceeded. POST /oauth/token has its own stricter limiter and its own message.

Media typeapplication/json

object

error

string

message

string

Examples

{
  "error": "Too Many Requests",
  "message": "Too many requests. Please slow down and try again shortly."
}

{
  "error": "Too Many Requests",
  "message": "Too many authentication attempts. Please try again in a few minutes."
}