---
title: "Create a payee link"
method: POST
path: "/api/v1/payee-links"
tags: ["Counterparties"]
---

# Create a payee link

`POST /api/v1/payee-links`

## Request

- Base URL: `https://www.vestiarion.xyz`
- URL: `https://www.vestiarion.xyz/api/v1/payee-links`
- Auth: HTTP bearer

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`.

## Request body

- CreatePayeeLinkRequest: Who the link is for.
  - `counterpartyId` string, required: 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.

## Response `201`

Created

- CreatePayeeLinkResponse
  - `data` object, required: 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.
    - `id` string, required: The link's own id. It is not the link: that is `url`.
    - `counterpartyId` string, required
    - `url` string, required: 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.
    - `expiresAt` string, required: 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.

## Other responses

- `400`: invalid_request
- `401`: unauthorized
- `403`: forbidden
- `429`: rate_limited
- `500`: internal

---

[API](https://skmtc.dev/vestiarion/apis/vestiarion-api.md) · [All operations](https://skmtc.dev/vestiarion/apis/vestiarion-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vestiarion/apis/vestiarion-api/revisions/fd2f589dac9b?raw)