Skip to content
VestiarionDocs

API reference

Create a payee link

POST/api/v1/payee-links

Makes a one-time link where a vendor or contractor enters the address they are paid at, recorded in the ledger as payee_link_created with via: "api" and the key's id. Send url to the payee yourself. It is in this answer only, since Vestiarion keeps just its hash, and the answer is sent with Cache-Control: no-store. The link works once and expires after 7 days.

The address the payee enters waits for a person in the workspace to confirm it on Counterparties; until then the agent pays nothing to it. Making a link revokes the payee's unused one, so only the newest works. For the same reason this operation keeps no outcome for an Idempotency-Key, which would store the link: a repeat makes a new link. A counterpartyId the workspace does not hold, or a client's, answers 400.

Send a workspace API key with read and write access as Authorization: Bearer …. A read-only key gets 403.

Parameters

No parameters.

Request body

Example
application/json
{
  "counterpartyId": "26d6ffed-356d-474a-8d42-89bc942f6b4e"
}
Fields
  • counterpartyIdstring

    The id of the vendor or contractor who is to enter the address they are paid at. A client gets no link: the agent never pays one.

Try it

Try it is off for operations that add records: run the sample with your own key.

Code samples

cURL
curl "https://www.vestiarion.xyz/api/v1/payee-links" \
  -X POST \
  -H "Authorization: Bearer $VESTIARION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"counterpartyId":"26d6ffed-356d-474a-8d42-89bc942f6b4e"}'

Response

Example
201 · application/json
{
  "data": {
    "id": "0810c2f3-dc6b-487e-aff5-63297ad33813",
    "counterpartyId": "26d6ffed-356d-474a-8d42-89bc942f6b4e",
    "url": "https://www.vestiarion.xyz/payee/vxp_avUyHXYqUlnt1OMB323j4N6Xv3H5lKzjZRNvbm1hfc4",
    "expiresAt": "2026-10-10T15:42:04.28+00:00"
  }
}
Fields
  • dataobject

    A one-time link for a payee to enter the address they are paid at. That address waits for a person in the workspace to confirm it before the agent pays to it.

    4 fields in data
    • idstring

      The link's own id. It is not the link: that is url.

    • counterpartyIdstring
    • urlstring

      The one-time page where the payee enters their address. It is in this answer only: Vestiarion keeps just its hash. Send it to the payee yourself.

    • expiresAtstring

      When the link stops working, 7 days after it was made. It also stops once the payee has used it, or a newer link replaces it.

Errors

StatusCodeWhen
400invalid_requestAn invalid limit or cursor, a filter value outside its allowed values, or a request body that does not validate. The message names the parameter or the field, and lists the accepted values.
401unauthorizedNo key, or a malformed, unknown or revoked one: "A valid API key is required."
403forbiddenThe key's scopes do not cover this route: "This key cannot do that." Or, on a write, the person who created the key can no longer add records: "This key's issuer can no longer add records in this workspace."
429rate_limitedToo many requests; wait as long as Retry-After says before trying again.
500internalAn unexpected server error. Implementation details are not exposed.