Skip to content
Pipevest Developers

Portfolios

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.

A Portfolio encapsulates a set of assets and aggregates their performance over time. This document will guide you on how to create, update and get ortfolio details.

Creating an Portfolio

Section titled “Creating an Portfolio”

To create an account:

Terminal window
  curl --request POST \
    --url https://api.pipevest.com/v1/portfolio\
    --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"}'

Updating Portfolios

Section titled “Updating Portfolios”

If you need to change an portfolio’s details:

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

Adding an asset to a Portfolio

Section titled “Adding an asset to a Portfolio”

Refer to Assets documentation to learn how to add an asset to a portfolio.

Retrieving Portfolios

Section titled “Retrieving Portfolios”

Portfolios with an accountId were automatically created by the Pipevest system. Wherein there is no accountId, the Portfolio was manually created via the API and does not have an associated Account.

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

  • A list of portfolio
  • An portfolio by a given Id

List of Portfolios

Section titled “List of Portfolios”
Terminal window
  curl --request GET \
    --url https://api.pipevest.com/v1/portfolio?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' \

Portfolio by Id

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

Entity Reference

Section titled “Entity Reference”
Property Definition
portfolioId Unique portfolio identifier
customerId Unique customer identifier
currency Associated currency
investmentAmount The total amount invested into an asset or group of assets
marketValue The current market value of an asset or group of assets
performance The performance of all the assets under the portfolio
status Current status of the portfolio
investmentType Investment type associated with the account
createdAt Created at unix timestamp
updatedAt Updated at unix timestamp

Pipevest created Portfolios

Section titled “Pipevest created Portfolios”
Property Definition
accountId Unique account identifier

Status

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

Webhook Subscriptions

Section titled “Webhook Subscriptions”
Subscription Definition Domain
PORTFOLIO Only events that deal with portfolio Portfolios
PORTFOLIO.CREATED Triggered when a portfolio is created Portfolios
PORTFOLIO.UPDATED Triggered when a portfolio is updated Portfolios