Skip to content
Pipevest Developers

Customers

Customers are the people your organization invests on behalf of. This guide covers how to create, update, and retrieve customers. All customer identifiers are CUID strings (e.g. clx0a1b2c3d4e5f6g7h8i9j0k).

Creating customers

Section titled “Creating customers”
Terminal window
  curl --request POST \
    --url https://api.staging.pipevest.com/v1/customers \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <access-token>' \
    --header 'x-client-id: <client-id>' \
    --data '{
      "firstName": "John",
      "lastName": "Doe",
      "msisdn": "260971234567",
      "identificationType": "NATIONAL_ID",
      "identificationNumber": "123456/78/9"
    }'
{
  "message": "Customer created successfully",
  "data": {
    "id": "clx0a1b2c3d4e5f6g7h8i9j0k",
    "organizationId": "clorgb2c3d4e5f6g7h8i9j0k1",
    "firstName": "John",
    "lastName": "Doe",
    "msisdn": "260971234567",
    "isActive": true,
    "identificationNumber": "123456/78/9",
    "identificationType": "NATIONAL_ID",
    "referenceId": null,
    "createdAt": "2026-07-15T08:00:00.000Z",
    "updatedAt": "2026-07-15T08:00:00.000Z"
  }
}

Only firstName and lastName are required. identificationType must be one of SSN, PASSPORT, DRIVER_LICENSE, NATIONAL_ID, TAX_ID or OTHER. msisdn must be 7–15 digits.

Reference Id

Section titled “Reference Id”

You may provide an optional referenceId (a string, max 100 chars) to match the customer against your own records.

Terminal window
  curl --request POST \
    --url https://api.staging.pipevest.com/v1/customers \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <access-token>' \
    --header 'x-client-id: <client-id>' \
    --data '{"firstName": "John", "lastName": "Doe", "referenceId": "acme-cust-000123"}'

Updating customers

Section titled “Updating customers”

Update a customer with a PATCH request to /customers/{id}, where {id} is the customer’s CUID. Send only the fields you want to change. Returns HTTP 200.

Terminal window
  curl --request PATCH \
    --url https://api.staging.pipevest.com/v1/customers/clx0a1b2c3d4e5f6g7h8i9j0k \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <access-token>' \
    --header 'x-client-id: <client-id>' \
    --data '{"firstName": "Jonathan", "lastName": "Doe"}'

Activating or deactivating a customer

Section titled “Activating or deactivating a customer”

A customer’s active state is controlled by the boolean isActive field (default true). Set it to false to deactivate.

Terminal window
  curl --request PATCH \
    --url https://api.staging.pipevest.com/v1/customers/clx0a1b2c3d4e5f6g7h8i9j0k \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <access-token>' \
    --header 'x-client-id: <client-id>' \
    --data '{"isActive": false}'

Retrieving customers

Section titled “Retrieving customers”

You can retrieve either a paginated list of customers or a single customer by ID.

List of customers

Section titled “List of customers”
Terminal window
  curl --request GET \
    --url 'https://api.staging.pipevest.com/v1/customers?page=1&limit=10' \
    --header 'Authorization: Bearer <access-token>' \
    --header 'x-client-id: <client-id>'
{
  "data": [
    { "id": "clx0a1b2c3d4e5f6g7h8i9j0k", "firstName": "John", "lastName": "Doe", "isActive": true }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 1, "totalPages": 1 }
}

Customer by Id

Section titled “Customer by Id”
Terminal window
  curl --request GET \
    --url https://api.staging.pipevest.com/v1/customers/clx0a1b2c3d4e5f6g7h8i9j0k \
    --header 'Authorization: Bearer <access-token>' \
    --header 'x-client-id: <client-id>'

A customer that does not exist (or does not belong to your organization) returns HTTP 404.

Field reference

Section titled “Field reference”
Property Definition
id Unique customer identifier (CUID string)
organizationId The organization the customer belongs to
firstName The customer’s first name (required, ≤ 100 chars)
lastName The customer’s last name (required, ≤ 100 chars)
msisdn Mobile number, 7–15 digits (optional)
isActive Whether the customer is active (boolean, default true)
identificationType One of SSN, PASSPORT, DRIVER_LICENSE, NATIONAL_ID, TAX_ID, OTHER
identificationNumber Identification document number (optional, ≤ 50 chars)
referenceId Your external reference for the customer (optional, ≤ 100 chars)
createdAt Created-at timestamp
updatedAt Updated-at timestamp