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 Request
  • Sell Request

​
Purchase Request

Make a POST request to /requests/purchase

  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

Make a POST request to /requests/sell

  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:

Make a PUT request to /requests

  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

Make a GET request to /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' \
This endpoint can be paginated and sorted.

​
Request by Id

Make a GET request to /requests/{requestId} 

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

​
Entity Reference

PropertyDefinition
requestIdUnique request identifier
customerIdUnique customer identifier
symbolThe symbol associated by the instrument
requestTypeThe type of request being made
statusThe status of the request
currencyAssociated currency
isRecurringDetermines whether the request should be in recurring mode
scheduleThe recurring schedule in which the instrument should be purchased
createdAtCreated at unix timestamp
updatedAtUpdated at unix timestamp

​
Purchase Request Entity

Includes the additional properties:
PropertyDefinition
instrumentIdUnique instrument identifier
purchaseAmountThe total purchase amount for an asset or group of assets

​
Sell Request Entity

Includes the additional properties:
PropertyDefinition
assetIdUnique asset identifier
sellAmountThe total amount to sell from an asset or group of assets
sellPercentageThe percentage amount to sell from an asset or group of assets

​
Status

NameDefinition
PENDINGThe request is currently in progress
COMPLETEDThe request has complete processing
CANCELEDThe request was cancelled
ERRORThe request ended in an error

​
Request Type

NameDefinition
PURCHASESets the request to purchase mode
SELLSets the request to sell mode

​
Webhook Subscriptions

SubscriptionDefinitionDomain
REQUESTOnly events that deal with requestsRequests
REQUEST.CREATEDTriggered when a request is createdRequests
REQUEST.UPDATEDTriggered when a request is updatedRequests