Skip to content
Pipevest Developers

Accounts

Planned — on our roadmap. This capability is documented so you can design your integration ahead of time. It is not yet enabled to call; for initial go-live, investment flows transact via USSD. If it is part of your integration plan, contact us. See what’s available today.

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

Section titled “Creating an Account”

To create an account:

Terminal window
  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"}'

Updating Accounts

Section titled “Updating Accounts”

If you need to change an account’s details:

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

Retrieving Accounts

Section titled “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

Section titled “List of Accounts”
Terminal window
  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' \

Account by Id

Section titled “Account by Id”
Terminal window
  curl --request GET \
    --url https://api.pipevest.com/v1/accounts/123456\
    ...

Creation Side Effects

Section titled “Creation Side Effects”

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

  1. A Portfolio linked to the account.

Entity Reference

Section titled “Entity Reference”
Property Definition
accountId Unique account identifier
customerId Unique customer identifier
status Current status of the account
investmentType Investment type associated with the account
currency Associated currency
createdAt Created at unix timestamp
updatedAt Updated at unix timestamp

Status

Section titled “Status”
Name Definition
ACTIVE Account is currently active and able to trade
SUSPENDED Account has been temporarily suspended, and is unable to trade.
CLOSED Account has been permanently prevented from trading

Webhook Subscriptions

Section titled “Webhook Subscriptions”
Subscription Definition Domain
ACCOUNT Only events that deal with accounts Accounts
ACCOUNT.CREATED Triggered when an account is created Accounts
ACCOUNT.UPDATED Triggered when an account is updated Accounts