Ask the account's owners to approve a transfer

File a transfer for an acting seat on the paying account to authorize.

This is the path for a seat that may not move money itself: nothing is sent until an owner approves by signing the transfer.

POST /api/v1/transfer_requests

Ask the account's owners to approve a transfer

cURL

curl --request POST \
  --url https://api.example.com/api/v1/transfer_requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contactId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "quoteId": "<string>",
  "invoiceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "amount": 123,
  "memo": "<string>",
  "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

202

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "requested",
  "txHash": "<string>",
  "transactionId": "<string>",
  "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "appId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "requestedByUserId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "contactId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "quoteId": "<string>",
  "invoiceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "amount": 123,
  "memo": "<string>",
  "requestedTime": "2023-11-07T05:31:56Z",
  "chatId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "approvalUrl": "<string>"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key · string | null

x-api-key · string | null

Body

application/json

Body of POST /transfer_requests.

accountId is the account the money leaves — a company a teammate holds a seat on. Omitted means their own account.

contactId · string<uuid> | null

quoteId · string | null

invoiceId · string<uuid> | null

amount · number | null

memo · string | null

accountId · string<uuid> | null

Response

202

application/json

Successful Response

One outcome shape for both ways a transfer attempt can end.

Spent straight away: txHash only. Needs approval: the request that was filed, with the deep link to approve it. transactionId appears once an approved transfer has been reported back. A decline reason is not a field — it is a message in chatId, the request's thread.

id · string<uuid> | null

status · enum<string> | null

Client-facing status of a transfer_request proposal.

The record is a proposal (seven statuses); this is the short vocabulary the API keeps for the agent and the web app, mapped from ProposalStatus by :meth:from_proposal.

Available options: requested, approved, declined, failed

txHash · string | null

transactionId · string | null

accountId · string<uuid> | null

appId · string<uuid> | null

requestedByUserId · string<uuid> | null

contactId · string<uuid> | null

quoteId · string | null

invoiceId · string<uuid> | null

amount · number | null

memo · string | null

requestedTime · string<date-time> | null

chatId · string<uuid> | null

approvalUrl · string | null