Creating a customer is the crucial step in enabling global investment access via Pipevest’s API. This document will guide you on how to create, update and get customer details.

​
Creating Customers

Make a POST request to /customers

  curl --request POST \
    --url https://api.pipevest.com/v1/customers\
    --header 'Authorization: Bearer 123456' \
    --header 'Content-Digest: sha-512=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:' \
    --header 'Content-Length: 18' \
    --header 'Content-Type: application/json' \
    --header 'Signature: sig1=:OTEyMjY4...A5NTNDMEQ=:' \
    --header 'Signature-Input: sig1=("Authorization" "Content-Digest" "Content-Length" "Content-Type" "X-Client-Id" "X-Idempotency-Key" "@method" "@target-uri" "@path" "@query");keyid="staging-pipevest-ed25519";created=1732893484;expires=1732893584' \
    --header 'X-Client-Id: 123456' \
    --header 'X-Idempotency-Key: 123456' \
    ...
    --data '{"firstName": "John", "lastName": "Doe"}'

Successfully creating a customer will result in some side effects.

​
Reference Id

When creating a user, you can provide an optional referenceId. This unique identifier should be used to externally match the customer.

  curl --request POST \
    --url https://api.pipevest.com/v1/customers\
    ...
    --data '{"firstName": "John", "lastName": "Doe", "referenceId": 123456}'

​
Updating Customers

If you need to change the customers details, you can simply update their details.

Make a PUT request to /customers

  curl --request PUT \
    --url https://api.pipevest.com/v1/customers\
    ...
    --data '{"customerId": 123456, "firstName": "Dohn", "lastName": "Joe"}'

​
Updating Status

A customer by default has an ACTIVE status. If you decide to change the customer’s status, do keep in mind of the side effects of this operation.

  curl --request PUT \
    --url https://api.pipevest.com/v1/customers\
    ...
    --data '{"customerId": 123456, "status": "CLOSED"}'

Successfully updating a customer’s status can result in some side effects.

​
Retrieving Customers

When requesting customer details you can do so either by getting:

  • A list of customers
  • A customer by a given Id

​
List of Customers

Make a GET request to /customers.

  curl --request GET \
    --url https://api.pipevest.com/v1/customers\
    --header 'Authorization: Bearer 123456' \
    --header 'Signature: sig1=:OTEyMjY4...A5NTNDMEQ=:' \
    --header 'Signature-Input: sig1=("Authorization" "Content-Digest" "Content-Length" "Content-Type" "X-Client-Id" "X-Idempotency-Key" "@method" "@target-uri" "@path" "@query");keyid="staging-pipevest-ed25519";created=1732893484;expires=1732893584' \
    --header 'X-Client-Id: 123456' \
This endpoint can be paginated and sorted.

​
Customer by Id

Make a GET request to /customers/{customerId} 

  curl --request GET \
    --url https://api.pipevest.com/v1/customers/123456\
    ...

​
Creation Side Effects

When a customer is created, the following resources are also created:

  1. Account(s) for the customer with the default organizations Investment Types.
  2. A Portfolio linked to each account.

​
Update Side Effects

When updating a customer’s status to SUSPENDED or CLOSED, the following actions will also take place:

  1. Account(s) status will be updated to match the customer status.
  2. Portfolio(s) status will be updated to match the customer status.

In the case of updating to ACTIVE, you will have to explicitly update the Accounts and Portfolios

​
Entity Reference

PropertyDefinition
customerIdUnique customer identifier
firstNameThe customers first name
lastNameThe customers last name
statusThe customers current status
referenceIdExternally provided unique identifier
createdAtCreated at unix timestamp
updatedAtUpdated at unix timestamp

​
Status

NameDefinition
ACTIVECustomer is currently active and able to trade
SUSPENDEDCustomer has been temporarily suspended, and is unable to trade.
CLOSEDCustomer has been permanently blocked from trading

​
Webhook Subscriptions

SubscriptionDefinitionDomain
CUSTOMEROnly events that deal with customersCustomers
CUSTOMER.CREATEDTriggered when a customer is createdCustomers
CUSTOMER.UPDATEDTriggered when a customer is updatedCustomers