Requests allow the purchase of Instruments and the sell of Assets.
This document will guide you on how to create, update and get request details.
Creating a Request
There are 2 types of requests:
Purchase RequestSell Request
Purchase Request
curl --request POST \
--url https://api.pipevest.com/v1/requests/purchase\
--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", "instrumentId": 123456, "purchaseAmount": 100 }'
Sell Request
curl --request POST \
--url https://api.pipevest.com/v1/requests/purchase/sell\
...
--data '{"customerId": 123456, "currency": "ZMW", "assetId": 123456, "sellAmount": 100 }'
Instead of sellAmount, a sellPercentage can be provided.
Recurring Requests
Optionally, requests can be set to recurring mode:
curl --request POST \
--url https://api.pipevest.com/v1/requests/purchase/purchase\
...
--data '{"customerId": 123456,..., "isRecurring": true, "schedule": "WEEKLY" }'
Updating Requests
If you need to cancel a request:
curl --request PUT \
--url https://api.pipevest.com/v1/requests\
...
--data '{"shouldCancelRequest": true}'
Retrieving Requests
When requesting account details you can do so either by getting:
- A list of requests
- An account by a given Id
List of Requests
curl --request GET \
--url https://api.pipevest.com/v1/requests?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' \
Request by Id
curl --request GET \
--url https://api.pipevest.com/v1/requests/123456\
...
Entity Reference
| Property | Definition |
|---|
requestId | Unique request identifier |
customerId | Unique customer identifier |
symbol | The symbol associated by the instrument |
requestType | The type of request being made |
status | The status of the request |
currency | Associated currency |
isRecurring | Determines whether the request should be in recurring mode |
schedule | The recurring schedule in which the instrument should be purchased |
createdAt | Created at unix timestamp |
updatedAt | Updated at unix timestamp |
Purchase Request Entity
Includes the additional properties:
| Property | Definition |
|---|
instrumentId | Unique instrument identifier |
purchaseAmount | The total purchase amount for an asset or group of assets |
Sell Request Entity
Includes the additional properties:
| Property | Definition |
|---|
assetId | Unique asset identifier |
sellAmount | The total amount to sell from an asset or group of assets |
sellPercentage | The percentage amount to sell from an asset or group of assets |
Status
| Name | Definition |
|---|
PENDING | The request is currently in progress |
COMPLETED | The request has complete processing |
CANCELED | The request was cancelled |
ERROR | The request ended in an error |
Request Type
| Name | Definition |
|---|
PURCHASE | Sets the request to purchase mode |
SELL | Sets the request to sell mode |
Webhook Subscriptions
| Subscription | Definition | Domain |
|---|
REQUEST | Only events that deal with requests | Requests |
REQUEST.CREATED | Triggered when a request is created | Requests |
REQUEST.UPDATED | Triggered when a request is updated | Requests |
