# Get the payee lock's evidence

`GET /api/v1/payee-lock/evidence`

Every payout address change in a period, in the format `vestiarion-payee-lock-evidence/1`: who entered it, how it was checked and by whom, whether a second person stood behind it, what it held back, and the first payment to it, each fact citing the signed entries it rests on, which the document carries in full with the workspace's public keys. It is the file the evidence pack's Download signed JSON gives, with members named by user id, never by email.

Days are whole UTC days; leave out `from` or `to` for an open end. A day that does not read, or a `from` after `to`, answers `400`, as does a period whose answer would be over 4 MB: ask for a shorter one. Text that came from outside, such as a payee's name, is carried as data.

Send a [workspace API key](https://www.vestiarion.xyz/docs/get-started/authentication) as `Authorization: Bearer <key>`.

## Parameters

| Name | In | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `from` | query | string | Optional | — | — | The first day, as `YYYY-MM-DD`, in UTC. Leave it out to start from the first change. |
| `to` | query | string | Optional | — | — | The last day, included, as `YYYY-MM-DD`, in UTC. Leave it out to run to now. |

## Code samples

```bash
curl "https://www.vestiarion.xyz/api/v1/payee-lock/evidence" \
  -H "Authorization: Bearer $VESTIARION_API_KEY"
```

## Response

Example, `200` `application/json`:

```json
{
  "data": {
    "format": "vestiarion-payee-lock-evidence/1",
    "exportedAt": "2026-10-25T09:00:00.000Z",
    "workspace": {
      "slug": "northstar-studio",
      "name": "Northstar Studio"
    },
    "network": {
      "id": "arc-testnet",
      "label": "Arc testnet"
    },
    "period": {
      "from": "2026-10-01",
      "to": "2026-10-31"
    },
    "lock": {
      "now": {
        "on": true,
        "coolingHours": 24
      },
      "changes": [
        {
          "at": "2026-10-01T08:00:00.000Z",
          "by": {
            "kind": "member",
            "userId": "4b7e0c1a-2d3f-4e5a-8b6c-7d8e9f0a1b01",
            "email": null
          },
          "from": {
            "on": false,
            "coolingHours": 0
          },
          "to": {
            "on": true,
            "coolingHours": 24
          },
          "entry": 5601
        }
      ]
    },
    "summary": {
      "changes": 1,
      "confirmed": 1,
      "confirmedWithRecord": 1,
      "confirmedBySecondPerson": 1,
      "heldWhileUnconfirmed": 0,
      "heldForTheWait": 0,
      "heldAsNewPayee": 0,
      "paid": 1,
      "paidOnlyAfterConfirmation": 1
    },
    "changes": [
      {
        "counterparty": {
          "id": "7d1e4c2a-5b3f-4e8a-9c61-2f0a8b3d4c01",
          "name": "Harbor Print Co."
        },
        "change": {
          "at": "2026-10-02T09:00:00.000Z",
          "from": "0x5a1b2c3d4e5f60718293a4b5c6d7e8f901234567",
          "to": "0x8c4f2e1d0b9a87766554433221100ffeeddccbba",
          "chain": "ARC-TESTNET",
          "enteredBy": {
            "kind": "member",
            "userId": "4b7e0c1a-2d3f-4e5a-8b6c-7d8e9f0a1b01",
            "email": null
          },
          "entry": 5605
        },
        "confirmation": {
          "at": "2026-10-02T09:40:00.000Z",
          "by": {
            "kind": "member",
            "userId": "4b7e0c1a-2d3f-4e5a-8b6c-7d8e9f0a1b02",
            "email": null
          },
          "via": "confirm",
          "record": {
            "method": "call",
            "methodLabel": "Called them on a number we had before",
            "contact": "Harbor Print's accounts line, from the vendor file",
            "contactOnFileBefore": true,
            "note": "Read back the new address on the call."
          },
          "secondPerson": true,
          "soloConfirmation": false,
          "byGiver": false,
          "giverUnknown": false,
          "waitHours": 24,
          "payableFrom": "2026-10-03T09:00:00.000Z",
          "lookalikeOf": [],
          "looksLikeEarlier": null,
          "entry": 5606
        },
        "holds": [],
        "firstPayment": {
          "at": "2026-10-03T15:20:00.000Z",
          "amount": 1250,
          "currency": "USDC",
          "txRef": "0x51713792df8660fed8ab6328e9b5023d1d80dcc566e5512abdcd7ef4eb1b92be",
          "txUrl": "https://explorer.testnet.arc.io/tx/0x51713792df8660fed8ab6328e9b5023d1d80dcc566e5512abdcd7ef4eb1b92be",
          "decidedBy": "person",
          "subject": {
            "kind": "invoice",
            "id": "7d1e4c2a-5b3f-4e8a-9c61-2f0a8b3d4e51"
          },
          "entry": 5610
        },
        "checks": {
          "recordKept": true,
          "contactOnFileBefore": true,
          "secondPerson": true,
          "paidAfterConfirmation": true,
          "paidAfterWait": true
        }
      }
    ],
    "signedEntryProves": "A signed entry proves who recorded what, and when. It does not prove the goods were good or the work was done.",
    "checkAnEntry": [
      "body_hash = sha256(canonical JSON of { actor, domain, action, summary, detail }, keys sorted)",
      "signature = Ed25519 over the 32 bytes of body_hash, by the key signing_key_id names",
      "hash = sha256(prev_hash || body_hash || signature), the hex strings joined"
    ],
    "keys": [
      {
        "id": "36e3209ae2e6a600",
        "status": "active",
        "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAhXbIpeLpKB5bbwxtRVDFBlWIDaY3sitQ9KiQ0xCR7No=\n-----END PUBLIC KEY-----\n"
      }
    ],
    "entries": [
      {
        "seq": 5601,
        "id": "4c91f0f4-911a-4545-8288-0db0bc9e02b8",
        "ts": "2026-10-01T08:00:00.000Z",
        "actor": "human",
        "domain": "system",
        "action": "payee_lock_changed",
        "summary": "Turned the payee lock on, with a 24-hour wait",
        "detail": {
          "by": "4b7e0c1a-2d3f-4e5a-8b6c-7d8e9f0a1b01",
          "from": {
            "on": false,
            "coolingHours": 0
          },
          "to": {
            "on": true,
            "coolingHours": 24
          }
        },
        "body_hash": "885a533140980dec04bcd50c470e75d411c28ce68a93c82faf03954b6ab8f368",
        "signature": "12afb9acc4ac110589546ef7f2a8eb8df4312c8a72295159cdbd94be406abe8e737093639f9c52ca49e62ad298b9721b9968a3db9eda98df003a399f18c78b0c",
        "prev_hash": "f930fef40d20e33527aea73c7a45b25da454cddb7ed988f4428566c590afd18a",
        "hash": "e0060f2d92de74e98a2f37aa7fca828b96325cd810ea0f85b55e7367c6c900d9",
        "signing_key_id": "36e3209ae2e6a600",
        "check": {
          "ok": true
        }
      },
      {
        "seq": 5605,
        "id": "2ebe4be1-9898-4a8a-a182-166563617e2c",
        "ts": "2026-10-02T09:00:00.000Z",
        "actor": "human",
        "domain": "compliance",
        "action": "counterparty_address_changed",
        "summary": "Changed Harbor Print Co.'s payout address",
        "detail": {
          "by": "4b7e0c1a-2d3f-4e5a-8b6c-7d8e9f0a1b01",
          "counterpartyId": "7d1e4c2a-5b3f-4e8a-9c61-2f0a8b3d4c01",
          "from": "0x5a1b2c3d4e5f60718293a4b5c6d7e8f901234567",
          "to": "0x8c4f2e1d0b9a87766554433221100ffeeddccbba",
          "chain": "ARC-TESTNET"
        },
        "body_hash": "32deece8f6598ac091688f95cc7650bf4b024509accc6c8bc08d02c24fbc7f8c",
        "signature": "118fa4acab75d62884243ec3aa11a1069e3a3c8b7446d92b2b212515e89743e64bf7203888218494ca1576cf3f8346a2859853d060ce522881150f0f5b9dd505",
        "prev_hash": "7890fd259c2a528efe9e2a57ff9b2d79385a4e7a684bcd2b12a1f93de96853d9",
        "hash": "5a4e61f31d16b7c1c873867f7a2b4756deb63d9d2624a6892ef1340b3ed3ae89",
        "signing_key_id": "36e3209ae2e6a600",
        "check": {
          "ok": true
        }
      },
      {
        "seq": 5606,
        "id": "386d19ec-b651-485a-9fcc-6dc7f3979a15",
        "ts": "2026-10-02T09:40:00.000Z",
        "actor": "human",
        "domain": "compliance",
        "action": "counterparty_address_confirmed",
        "summary": "Confirmed Harbor Print Co.'s new payout address",
        "detail": {
          "by": "4b7e0c1a-2d3f-4e5a-8b6c-7d8e9f0a1b02",
          "counterpartyId": "7d1e4c2a-5b3f-4e8a-9c61-2f0a8b3d4c01",
          "address": "0x8c4f2e1d0b9a87766554433221100ffeeddccbba",
          "chain": "ARC-TESTNET",
          "via": "confirm",
          "verification": {
            "method": "call",
            "contact": "Harbor Print's accounts line, from the vendor file",
            "contactOnFileBefore": true,
            "note": "Read back the new address on the call."
          },
          "payeeLock": {
            "coolingHours": 24
          }
        },
        "body_hash": "7c040055d7b5699ea69746fd510b4a6870b8b62f40c989c82e070f5bee081482",
        "signature": "9d4c736dcab1e695a202ca4d879346525d786ffb9937d4e4897c4ab212a8767240341e79e31028d15744b046fbfeff9666726576f1fac3df5ccbde06e9727301",
        "prev_hash": "5a4e61f31d16b7c1c873867f7a2b4756deb63d9d2624a6892ef1340b3ed3ae89",
        "hash": "ecedf7e736213c37131c6f2fdf3f5dae528f9d5b687b08122e9a6335dbcce355",
        "signing_key_id": "36e3209ae2e6a600",
        "check": {
          "ok": true
        }
      },
      {
        "seq": 5610,
        "id": "eab46f04-8b5a-44f1-803b-98e6b0a80f72",
        "ts": "2026-10-03T15:20:00.000Z",
        "actor": "human",
        "domain": "ap",
        "action": "approval_paid",
        "summary": "Approved and paid 1250 USDC to Harbor Print Co.",
        "detail": {
          "by": "4b7e0c1a-2d3f-4e5a-8b6c-7d8e9f0a1b02",
          "invoiceId": "7d1e4c2a-5b3f-4e8a-9c61-2f0a8b3d4e51",
          "counterpartyId": "7d1e4c2a-5b3f-4e8a-9c61-2f0a8b3d4c01",
          "amount": 1250,
          "currency": "USDC",
          "amountPaid": 1250,
          "discountTaken": 0,
          "overrode": "held",
          "txRef": "0x51713792df8660fed8ab6328e9b5023d1d80dcc566e5512abdcd7ef4eb1b92be",
          "status": "paid",
          "attempt": 1,
          "firstPayment": true,
          "approvals": [
            {
              "by": "4b7e0c1a-2d3f-4e5a-8b6c-7d8e9f0a1b03",
              "at": "2026-10-03T14:00:00.000Z"
            },
            {
              "by": "4b7e0c1a-2d3f-4e5a-8b6c-7d8e9f0a1b02",
              "at": "2026-10-03T15:20:00.000Z"
            }
          ],
          "twoApprovalsAbove": 1000
        },
        "body_hash": "dae21d642023e245c099621bc1a8a1689b0f6d243b62803f464b4e35859c8400",
        "signature": "035c519ac40e1dd2bbc7d70e08180b0e624cbc16df3b3a74c2a609c40c26cbe04f0d2a28bb01edbe1f0c0f5c9a52c76127f2c4affc71f7ae0fcdeac82f32b60b",
        "prev_hash": "87750f493b785c931c8c69551ad76a1418b935eb8d2704a5c0fca19833cf959e",
        "hash": "1bd91f4c85872fe824fc18dfb7409f1ce3bbe63728fe993d070a4e14ef03c070",
        "signing_key_id": "36e3209ae2e6a600",
        "check": {
          "ok": true
        }
      }
    ]
  }
}
```

**Fields**

- `data` (object, required): Every payout address change in a period, `vestiarion-payee-lock-evidence/1`, each fact citing the signed entries it rests on.
  - `format` (string, required) One of `vestiarion-payee-lock-evidence/1`.
  - `exportedAt` (string, required)
  - `workspace` (object, required): The workspace the document is of.
    - `slug` (string, required)
    - `name` (string, required)
  - `network` (object, required): The workspace's network.
    - `id` (string, required) One of `arc-testnet`, `arc-mainnet`.
    - `label` (string, required): The network's name, as the workspace's pages write it.
  - `period` (object, required): Whole UTC days, `YYYY-MM-DD`; null for an open end.
    - `from` (string, nullable, required)
    - `to` (string, nullable, required)
  - `lock` (object, required)
    - `now` (object, required): The payee lock's setting.
      - `on` (boolean, required)
      - `coolingHours` (number, required): Hours a changed address waits before it can be paid; 0 is no wait.
    - `changes` (array of object, required)
      - `at` (string, required)
      - `by` (any, required): Who did a step.
      - `from` (object, nullable, required): The payee lock's setting.
        - `on` (boolean, required)
        - `coolingHours` (number, required): Hours a changed address waits before it can be paid; 0 is no wait.
      - `to` (object, nullable, required): The payee lock's setting.
        - `on` (boolean, required)
        - `coolingHours` (number, required): Hours a changed address waits before it can be paid; 0 is no wait.
      - `entry` (integer, required)
  - `summary` (object, required)
    - `changes` (integer, required)
    - `confirmed` (integer, required)
    - `confirmedWithRecord` (integer, required)
    - `confirmedBySecondPerson` (integer, required)
    - `heldWhileUnconfirmed` (integer, required)
    - `heldForTheWait` (integer, required)
    - `heldAsNewPayee` (integer, required)
    - `paid` (integer, required)
    - `paidOnlyAfterConfirmation` (integer, required)
  - `changes` (array of object, required)
    - `counterparty` (object, required)
      - `id` (string, required)
      - `name` (string, nullable, required)
    - `change` (object, required)
      - `at` (string, required)
      - `from` (string, nullable, required)
      - `to` (string, nullable, required)
      - `chain` (string, nullable, required)
      - `enteredBy` (any, required): Who did a step.
      - `entry` (integer, required)
    - `confirmation` (object, nullable, required)
      - `at` (string, required)
      - `by` (any, required): Who did a step.
      - `via` (string, nullable, required): With Confirm address (`confirm`), or by approving a payment to it (`approval`).
      - `record` (object, nullable, required)
        - `method` (string, nullable, required) One of `call`, `message`, `in_person`, `other`.
        - `methodLabel` (string, nullable, required)
        - `contact` (string, nullable, required)
        - `contactOnFileBefore` (boolean, required)
        - `note` (string, nullable, required)
      - `secondPerson` (boolean, nullable, required)
      - `soloConfirmation` (boolean, required)
      - `byGiver` (boolean, required)
      - `giverUnknown` (boolean, required)
      - `waitHours` (number, nullable, required)
      - `payableFrom` (string, nullable, required)
      - `lookalikeOf` (array of object, required)
        - `id` (string, required)
        - `name` (string, nullable, required)
      - `looksLikeEarlier` (string, nullable, required)
      - `entry` (integer, required)
    - `holds` (array of object, required)
      - `at` (string, required)
      - `rule` (string, required)
      - `subject` (object, nullable, required)
        - `kind` (string, required) One of `invoice`, `milestone`.
        - `id` (string, required)
      - `entry` (integer, required)
    - `firstPayment` (object, nullable, required)
      - `at` (string, required)
      - `amount` (number, nullable, required)
      - `currency` (string, required)
      - `txRef` (string, required)
      - `txUrl` (string, nullable, required)
      - `decidedBy` (string, required) One of `person`, `agent`.
      - `subject` (object, nullable, required)
        - `kind` (string, required) One of `invoice`, `milestone`.
        - `id` (string, required)
      - `entry` (integer, required)
    - `checks` (object, required)
      - `recordKept` (boolean, nullable, required)
      - `contactOnFileBefore` (boolean, nullable, required)
      - `secondPerson` (boolean, nullable, required)
      - `paidAfterConfirmation` (boolean, nullable, required)
      - `paidAfterWait` (boolean, nullable, required)
  - `signedEntryProves` (string, required): What a signed entry proves, and what it does not.
  - `checkAnEntry` (array of string, required): How to check one entry alone: its body hash, its signature and its chain hash.
  - `keys` (array of object, required): The workspace's public keys, active and retired, each under its id: what the entries were signed with.
    - `id` (string, required): The first 16 hex characters of the SHA-256 of the key's public SPKI: a key counts only under this id.
    - `status` (string, required) One of `active`, `retired`.
    - `publicKeyPem` (string, required)
  - `entries` (array of object, required): Every entry the document cites, oldest first, in full, each with the server's check.
    - `seq` (integer, required)
    - `id` (string, nullable, required)
    - `ts` (string, required)
    - `actor` (string, required)
    - `domain` (string, required)
    - `action` (string, required)
    - `summary` (string, required)
    - `detail` (object, required)
    - `body_hash` (string, required)
    - `signature` (string, required)
    - `prev_hash` (string, required)
    - `hash` (string, required)
    - `signing_key_id` (string, nullable, required)
    - `check` (any, nullable, required): The server's check of this entry alone. A checker re-checks it rather than trust this field.

## Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_request` | An 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. |
| 401 | `unauthorized` | No key, or a malformed, unknown or revoked one: "A valid API key is required." |
| 403 | `forbidden` | The 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." |
| 429 | `rate_limited` | Too many requests; wait as long as `Retry-After` says before trying again. |
| 500 | `internal` | An unexpected server error. Implementation details are not exposed. |