An account for each organization’s default Investment Type is created when a customer is created. There is a 1 to 1 mapping between investment types and accounts. Meaning, for each investment type that a customer can access, there can only exist one account for it.

This document will guide you on how to create, update and get account details.

​
Creating an Account

To create an account:

Make a POST request to /accounts

  curl --request POST \
    --url https://api.pipevest.com/v1/accounts\
    --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 '{"customerId": 123456, "currency": "ZMW", "investmentTypes": "INTERNATIONAL_STOCKS"}'

Successfully creating an account will result in some side effects.

​
Updating Accounts

If you need to change an account’s details:

Make a PUT request to /accounts

  curl --request PUT \
    --url https://api.pipevest.com/v1/accounts\
    ...
    --data '{"accountId": 123456, "status": "ACTIVE", "currency": "USD"}'

​
Retrieving Accounts

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

  • A list of accounts
  • An account by a given Id

​
List of Accounts

Make a GET request to /accounts.

  curl --request GET \
    --url https://api.pipevest.com/v1/accounts?customerId=123456\
    --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.

​
Account by Id

Make a GET request to /accounts/{accountId} 

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

​
Creation Side Effects

When an account is created, the following resources are also created:

  1. A Portfolio linked to the account.

​
Entity Reference

PropertyDefinition
accountIdUnique account identifier
customerIdUnique customer identifier
statusCurrent status of the account
investmentTypeInvestment type associated with the account
currencyAssociated currency
createdAtCreated at unix timestamp
updatedAtUpdated at unix timestamp

​
Status

NameDefinition
ACTIVEAccount is currently active and able to trade
SUSPENDEDAccount has been temporarily suspended, and is unable to trade.
CLOSEDAccount has been permanently prevented from trading

​
Webhook Subscriptions

SubscriptionDefinitionDomain
ACCOUNTOnly events that deal with accountsAccounts
ACCOUNT.CREATEDTriggered when an account is createdAccounts
ACCOUNT.UPDATEDTriggered when an account is updatedAccounts