{"info":{"title":"Paygoro API","version":"1.0.0","description":"Programmatic access to the banking, treasury and bill-pay data in a Paygoro workspace.\n\nAuthenticate every request with an API key in the `Authorization` header: `Authorization: Bearer pgk_…`. Keys are created by workspace owners and admins under Settings → Developers, and carry scopes:\n\n- `companies:read` — List the legal entities in the workspace.\n- `accounts:read` — Read bank accounts and their balances.\n- `transactions:read` — Read transactions across all accounts.\n- `categories:read` — Read the workspace's transaction categories.\n- `bills:read` — Read bills (payable invoices) and their status.\n- `payees:read` — Read saved payees.\n- `payees:write` — Create, update, and delete saved payees.","contact":{"name":"Paygoro support","email":"support@paygoro.com"}},"servers":[{"url":"https://api.paygoro.com/v1"}],"tags":[{"name":"Workspace","description":"The workspace your key belongs to."},{"name":"Companies","description":"Legal entities in the workspace."},{"name":"Accounts","description":"Paygoro business accounts and connected external accounts."},{"name":"Transactions","description":"Bank transactions across all accounts."},{"name":"Categories","description":"Transaction categories."},{"name":"Bills","description":"Payable invoices in the bill-pay inbox."},{"name":"Payees","description":"Saved beneficiaries."}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"A Paygoro API key (`pgk_…`) sent as a bearer token."}}},"security":[{"apiKey":[]}],"openapi":"3.1.1","paths":{"/workspace":{"get":{"operationId":"getWorkspace","summary":"Get the current workspace","description":"Returns the workspace your API key belongs to and the scopes it carries. Useful as a connectivity check — it needs no scope.","tags":["Workspace"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Opaque resource id."},"name":{"type":"string"},"apiKey":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Opaque resource id."},"name":{"type":"string","description":"The label given to the key when created."},"scopes":{"type":"array","items":{"type":"string"},"description":"Scopes granted to this key."}},"required":["id","name","scopes"],"description":"The key that authenticated this request."}},"required":["id","name","apiKey"],"description":"The workspace the API key belongs to."}}}},"400":{"description":"400","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"BAD_REQUEST"},"status":{"const":400},"message":{"type":"string","default":"The request was malformed or failed validation."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"UNAUTHORIZED"},"status":{"const":401},"message":{"type":"string","default":"Missing, malformed, expired or revoked API key."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"status":{"const":403},"message":{"type":"string","default":"The API key does not have the scope this operation requires."},"data":{"type":"object","properties":{"requiredScopes":{"type":"array","items":{"type":"string"}}},"required":["requiredScopes"]}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"status":{"const":404},"message":{"type":"string","default":"No resource with this id exists in your workspace, or a `companyId` filter does not match one of your companies."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"429":{"description":"429","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"TOO_MANY_REQUESTS"},"status":{"const":429},"message":{"type":"string","default":"Rate limit exceeded. Retry after the `Retry-After` header."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}}},"security":[{"apiKey":[]}],"x-required-scopes":[]}},"/companies":{"get":{"operationId":"listCompanies","summary":"List companies","description":"Lists the legal entities in the workspace. Most other resources belong to a company; use these ids in `companyId` filters.","tags":["Companies"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Opaque resource id."},"name":{"type":"string","description":"Registered legal name."},"tradingName":{"anyOf":[{"type":"string"},{"type":"null"}]},"registrationNumber":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chamber of commerce / company registry number."},"vatNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 3166-1 alpha-2 country of incorporation."},"verificationStatus":{"enum":["NotStarted","Pending","Verified","WaitingForInformation","Refused"],"type":"string","description":"Know-your-business verification state for the Paygoro business account."},"createdAt":{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."}},"required":["id","name","tradingName","registrationNumber","vatNumber","country","verificationStatus","createdAt","updatedAt"],"description":"A legal entity in the workspace. Accounts, transactions, bills and payees all belong to a company."}}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"BAD_REQUEST"},"status":{"const":400},"message":{"type":"string","default":"The request was malformed or failed validation."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"UNAUTHORIZED"},"status":{"const":401},"message":{"type":"string","default":"Missing, malformed, expired or revoked API key."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"status":{"const":403},"message":{"type":"string","default":"The API key does not have the scope this operation requires."},"data":{"type":"object","properties":{"requiredScopes":{"type":"array","items":{"type":"string"}}},"required":["requiredScopes"]}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"status":{"const":404},"message":{"type":"string","default":"No resource with this id exists in your workspace, or a `companyId` filter does not match one of your companies."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"429":{"description":"429","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"TOO_MANY_REQUESTS"},"status":{"const":429},"message":{"type":"string","default":"Rate limit exceeded. Retry after the `Retry-After` header."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}}},"security":[{"apiKey":["companies:read"]}],"x-required-scopes":["companies:read"]}},"/accounts":{"get":{"operationId":"listAccounts","summary":"List accounts","description":"Lists every bank account in the workspace — Paygoro business accounts and connected external accounts — with current balances.","tags":["Accounts"],"parameters":[{"name":"companyId","in":"query","schema":{"type":"string","minLength":1,"description":"Restrict to one legal entity. Omit to include every entity in the workspace."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Opaque resource id."},"companyId":{"type":"string","minLength":1,"description":"Opaque resource id."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Account name as reported by the bank."},"nickname":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"User-chosen display name, when set."},"iban":{"anyOf":[{"type":"string"},{"type":"null"}]},"bic":{"anyOf":[{"type":"string"},{"type":"null"}]},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code, e.g. EUR."},"balance":{"anyOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","description":"Decimal amount as a string, e.g. \"1250.00\". Never a float."},{"type":"null"}],"description":"Booked balance. Null when the bank has not reported one yet."},"availableBalance":{"anyOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","description":"Decimal amount as a string, e.g. \"1250.00\". Never a float."},{"type":"null"}]},"balanceUpdatedAt":{"anyOf":[{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."},{"type":"null"}]},"type":{"enum":["depository","credit","other"],"type":"string"},"provider":{"enum":["paygoro","connected"],"type":"string","description":"`paygoro` for a Paygoro business account, `connected` for an external bank linked to the workspace."},"institutionName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Name of the bank holding the account."},"enabled":{"type":"boolean","description":"False when the user has hidden the account from views."},"createdAt":{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."}},"required":["id","companyId","name","nickname","iban","bic","currency","balance","availableBalance","balanceUpdatedAt","type","provider","institutionName","enabled","createdAt"],"description":"A bank account: a Paygoro business account or a connected external account."}}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"BAD_REQUEST"},"status":{"const":400},"message":{"type":"string","default":"The request was malformed or failed validation."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"UNAUTHORIZED"},"status":{"const":401},"message":{"type":"string","default":"Missing, malformed, expired or revoked API key."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"status":{"const":403},"message":{"type":"string","default":"The API key does not have the scope this operation requires."},"data":{"type":"object","properties":{"requiredScopes":{"type":"array","items":{"type":"string"}}},"required":["requiredScopes"]}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"status":{"const":404},"message":{"type":"string","default":"No resource with this id exists in your workspace, or a `companyId` filter does not match one of your companies."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"429":{"description":"429","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"TOO_MANY_REQUESTS"},"status":{"const":429},"message":{"type":"string","default":"Rate limit exceeded. Retry after the `Retry-After` header."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}}},"security":[{"apiKey":["accounts:read"]}],"x-required-scopes":["accounts:read"]}},"/accounts/{id}":{"get":{"operationId":"getAccount","summary":"Get an account","tags":["Accounts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"description":"Opaque resource id."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Opaque resource id."},"companyId":{"type":"string","minLength":1,"description":"Opaque resource id."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Account name as reported by the bank."},"nickname":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"User-chosen display name, when set."},"iban":{"anyOf":[{"type":"string"},{"type":"null"}]},"bic":{"anyOf":[{"type":"string"},{"type":"null"}]},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code, e.g. EUR."},"balance":{"anyOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","description":"Decimal amount as a string, e.g. \"1250.00\". Never a float."},{"type":"null"}],"description":"Booked balance. Null when the bank has not reported one yet."},"availableBalance":{"anyOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","description":"Decimal amount as a string, e.g. \"1250.00\". Never a float."},{"type":"null"}]},"balanceUpdatedAt":{"anyOf":[{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."},{"type":"null"}]},"type":{"enum":["depository","credit","other"],"type":"string"},"provider":{"enum":["paygoro","connected"],"type":"string","description":"`paygoro` for a Paygoro business account, `connected` for an external bank linked to the workspace."},"institutionName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Name of the bank holding the account."},"enabled":{"type":"boolean","description":"False when the user has hidden the account from views."},"createdAt":{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."}},"required":["id","companyId","name","nickname","iban","bic","currency","balance","availableBalance","balanceUpdatedAt","type","provider","institutionName","enabled","createdAt"],"description":"A bank account: a Paygoro business account or a connected external account."}}}},"400":{"description":"400","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"BAD_REQUEST"},"status":{"const":400},"message":{"type":"string","default":"The request was malformed or failed validation."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"UNAUTHORIZED"},"status":{"const":401},"message":{"type":"string","default":"Missing, malformed, expired or revoked API key."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"status":{"const":403},"message":{"type":"string","default":"The API key does not have the scope this operation requires."},"data":{"type":"object","properties":{"requiredScopes":{"type":"array","items":{"type":"string"}}},"required":["requiredScopes"]}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"status":{"const":404},"message":{"type":"string","default":"No resource with this id exists in your workspace, or a `companyId` filter does not match one of your companies."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"429":{"description":"429","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"TOO_MANY_REQUESTS"},"status":{"const":429},"message":{"type":"string","default":"Rate limit exceeded. Retry after the `Retry-After` header."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}}},"security":[{"apiKey":["accounts:read"]}],"x-required-scopes":["accounts:read"]}},"/transactions":{"get":{"operationId":"listTransactions","summary":"List transactions","description":"Lists transactions across the workspace, newest booking date first. Paginated; filter by account, date range, status, direction or category. For incremental sync, store the newest `updatedAt` you have seen and pass it as `updatedAfter`.","tags":["Transactions"],"parameters":[{"name":"companyId","in":"query","schema":{"type":"string","minLength":1,"description":"Restrict to one legal entity. Omit to include every entity in the workspace."},"allowEmptyValue":true,"allowReserved":true},{"name":"accountId","in":"query","schema":{"type":"string","minLength":1,"description":"Restrict to one account."},"allowEmptyValue":true,"allowReserved":true},{"name":"dateFrom","in":"query","schema":{"type":"string","format":"date","description":"Inclusive lower bound on the booking date."},"allowEmptyValue":true,"allowReserved":true},{"name":"dateTo","in":"query","schema":{"type":"string","format":"date","description":"Inclusive upper bound on the booking date."},"allowEmptyValue":true,"allowReserved":true},{"name":"status","in":"query","schema":{"enum":["pending","booked","rejected","released","canceled"],"type":"string"},"allowEmptyValue":true,"allowReserved":true},{"name":"side","in":"query","schema":{"enum":["debit","credit"],"type":"string"},"allowEmptyValue":true,"allowReserved":true},{"name":"categoryId","in":"query","schema":{"type":"string","minLength":1,"description":"Restrict to one category."},"allowEmptyValue":true,"allowReserved":true},{"name":"updatedAfter","in":"query","schema":{"type":"string","format":"date-time","description":"Only transactions created or changed after this instant. The building block for incremental sync."},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size, 1–100. Defaults to 50."},"allowEmptyValue":true,"allowReserved":true},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1,"description":"Opaque pagination cursor from a previous response's `nextCursor`."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Opaque resource id."},"companyId":{"type":"string","minLength":1,"description":"Opaque resource id."},"accountId":{"type":"string","minLength":1,"description":"Opaque resource id."},"amount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","description":"Unsigned amount in the transaction currency. Use `side` for direction."},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code, e.g. EUR."},"side":{"anyOf":[{"enum":["debit","credit"],"type":"string"},{"type":"null"}],"description":"`credit` = money in, `debit` = money out."},"status":{"enum":["pending","booked","rejected","released","canceled"],"type":"string"},"type":{"anyOf":[{"enum":["SepaCredit","SepaDirect","Card","InternalCredit","InternalDirectDebit","FeeCredit","FeeDebit","Check","Other"],"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bank-provided label or description."},"reference":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Payment reference / remittance information."},"counterpartyName":{"anyOf":[{"type":"string"},{"type":"null"}]},"counterpartyIban":{"anyOf":[{"type":"string"},{"type":"null"}]},"merchantName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cleaned merchant name from Paygoro's enrichment, when known."},"bookingDate":{"anyOf":[{"type":"string","format":"date","description":"Calendar date in YYYY-MM-DD format."},{"type":"null"}]},"valueDate":{"anyOf":[{"type":"string","format":"date","description":"Calendar date in YYYY-MM-DD format."},{"type":"null"}]},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Opaque resource id."},"name":{"type":"string"},"slug":{"type":"string"}},"required":["id","name","slug"],"description":"The category assigned to the transaction."},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."},"updatedAt":{"type":"string","format":"date-time","description":"Changes when the bank updates the row or a category is assigned. Poll with `updatedAfter` to sync incrementally."}},"required":["id","companyId","accountId","amount","currency","side","status","type","description","reference","counterpartyName","counterpartyIban","merchantName","bookingDate","valueDate","category","createdAt","updatedAt"],"description":"A bank transaction on one of the workspace's accounts."}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass as `cursor` to fetch the next page. `null` when this is the last page."}},"required":["data","nextCursor"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"BAD_REQUEST"},"status":{"const":400},"message":{"type":"string","default":"The request was malformed or failed validation."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"UNAUTHORIZED"},"status":{"const":401},"message":{"type":"string","default":"Missing, malformed, expired or revoked API key."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"status":{"const":403},"message":{"type":"string","default":"The API key does not have the scope this operation requires."},"data":{"type":"object","properties":{"requiredScopes":{"type":"array","items":{"type":"string"}}},"required":["requiredScopes"]}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"status":{"const":404},"message":{"type":"string","default":"No resource with this id exists in your workspace, or a `companyId` filter does not match one of your companies."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"429":{"description":"429","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"TOO_MANY_REQUESTS"},"status":{"const":429},"message":{"type":"string","default":"Rate limit exceeded. Retry after the `Retry-After` header."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}}},"security":[{"apiKey":["transactions:read"]}],"x-required-scopes":["transactions:read"]}},"/transactions/{id}":{"get":{"operationId":"getTransaction","summary":"Get a transaction","tags":["Transactions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"description":"Opaque resource id."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Opaque resource id."},"companyId":{"type":"string","minLength":1,"description":"Opaque resource id."},"accountId":{"type":"string","minLength":1,"description":"Opaque resource id."},"amount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","description":"Unsigned amount in the transaction currency. Use `side` for direction."},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code, e.g. EUR."},"side":{"anyOf":[{"enum":["debit","credit"],"type":"string"},{"type":"null"}],"description":"`credit` = money in, `debit` = money out."},"status":{"enum":["pending","booked","rejected","released","canceled"],"type":"string"},"type":{"anyOf":[{"enum":["SepaCredit","SepaDirect","Card","InternalCredit","InternalDirectDebit","FeeCredit","FeeDebit","Check","Other"],"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bank-provided label or description."},"reference":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Payment reference / remittance information."},"counterpartyName":{"anyOf":[{"type":"string"},{"type":"null"}]},"counterpartyIban":{"anyOf":[{"type":"string"},{"type":"null"}]},"merchantName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cleaned merchant name from Paygoro's enrichment, when known."},"bookingDate":{"anyOf":[{"type":"string","format":"date","description":"Calendar date in YYYY-MM-DD format."},{"type":"null"}]},"valueDate":{"anyOf":[{"type":"string","format":"date","description":"Calendar date in YYYY-MM-DD format."},{"type":"null"}]},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Opaque resource id."},"name":{"type":"string"},"slug":{"type":"string"}},"required":["id","name","slug"],"description":"The category assigned to the transaction."},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."},"updatedAt":{"type":"string","format":"date-time","description":"Changes when the bank updates the row or a category is assigned. Poll with `updatedAfter` to sync incrementally."}},"required":["id","companyId","accountId","amount","currency","side","status","type","description","reference","counterpartyName","counterpartyIban","merchantName","bookingDate","valueDate","category","createdAt","updatedAt"],"description":"A bank transaction on one of the workspace's accounts."}}}},"400":{"description":"400","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"BAD_REQUEST"},"status":{"const":400},"message":{"type":"string","default":"The request was malformed or failed validation."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"UNAUTHORIZED"},"status":{"const":401},"message":{"type":"string","default":"Missing, malformed, expired or revoked API key."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"status":{"const":403},"message":{"type":"string","default":"The API key does not have the scope this operation requires."},"data":{"type":"object","properties":{"requiredScopes":{"type":"array","items":{"type":"string"}}},"required":["requiredScopes"]}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"status":{"const":404},"message":{"type":"string","default":"No resource with this id exists in your workspace, or a `companyId` filter does not match one of your companies."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"429":{"description":"429","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"TOO_MANY_REQUESTS"},"status":{"const":429},"message":{"type":"string","default":"Rate limit exceeded. Retry after the `Retry-After` header."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}}},"security":[{"apiKey":["transactions:read"]}],"x-required-scopes":["transactions:read"]}},"/categories":{"get":{"operationId":"listCategories","summary":"List categories","description":"Lists the workspace's transaction categories, including the defaults Paygoro seeds. Categories are workspace-wide, not per company.","tags":["Categories"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Opaque resource id."},"name":{"type":"string"},"slug":{"type":"string","description":"URL-safe, unique within the workspace."},"color":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"isSystem":{"type":"boolean","description":"True for the default categories Paygoro seeds in every workspace."},"createdAt":{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."}},"required":["id","name","slug","color","description","isSystem","createdAt"],"description":"A transaction category defined in the workspace."}}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"BAD_REQUEST"},"status":{"const":400},"message":{"type":"string","default":"The request was malformed or failed validation."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"UNAUTHORIZED"},"status":{"const":401},"message":{"type":"string","default":"Missing, malformed, expired or revoked API key."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"status":{"const":403},"message":{"type":"string","default":"The API key does not have the scope this operation requires."},"data":{"type":"object","properties":{"requiredScopes":{"type":"array","items":{"type":"string"}}},"required":["requiredScopes"]}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"status":{"const":404},"message":{"type":"string","default":"No resource with this id exists in your workspace, or a `companyId` filter does not match one of your companies."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"429":{"description":"429","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"TOO_MANY_REQUESTS"},"status":{"const":429},"message":{"type":"string","default":"Rate limit exceeded. Retry after the `Retry-After` header."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}}},"security":[{"apiKey":["categories:read"]}],"x-required-scopes":["categories:read"]}},"/bills":{"get":{"operationId":"listBills","summary":"List bills","description":"Lists payable invoices in the bill-pay inbox, newest first. Paginated; filter by company or status.","tags":["Bills"],"parameters":[{"name":"companyId","in":"query","schema":{"type":"string","minLength":1,"description":"Restrict to one legal entity. Omit to include every entity in the workspace."},"allowEmptyValue":true,"allowReserved":true},{"name":"status","in":"query","schema":{"enum":["new","processing","extract_failed","pending_match","matched","pending_approval","approved","scheduled","paid","rejected","archived"],"type":"string"},"allowEmptyValue":true,"allowReserved":true},{"name":"updatedAfter","in":"query","schema":{"type":"string","format":"date-time","description":"Only bills created or changed after this instant."},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size, 1–100. Defaults to 50."},"allowEmptyValue":true,"allowReserved":true},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1,"description":"Opaque pagination cursor from a previous response's `nextCursor`."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Opaque resource id."},"companyId":{"type":"string","minLength":1,"description":"Opaque resource id."},"status":{"enum":["new","processing","extract_failed","pending_match","matched","pending_approval","approved","scheduled","paid","rejected","archived"],"type":"string"},"supplierName":{"anyOf":[{"type":"string"},{"type":"null"}]},"supplierIban":{"anyOf":[{"type":"string"},{"type":"null"}]},"invoiceNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"totalAmount":{"anyOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","description":"Decimal amount as a string, e.g. \"1250.00\". Never a float."},{"type":"null"}]},"vatAmount":{"anyOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","description":"Decimal amount as a string, e.g. \"1250.00\". Never a float."},{"type":"null"}]},"currency":{"anyOf":[{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code, e.g. EUR."},{"type":"null"}]},"invoiceDate":{"anyOf":[{"type":"string","format":"date","description":"Calendar date in YYYY-MM-DD format."},{"type":"null"}]},"dueDate":{"anyOf":[{"type":"string","format":"date","description":"Calendar date in YYYY-MM-DD format."},{"type":"null"}]},"paymentReference":{"anyOf":[{"type":"string"},{"type":"null"}]},"matchedTransactionId":{"anyOf":[{"type":"string","minLength":1,"description":"Opaque resource id."},{"type":"null"}],"description":"The transaction that settled this bill, once matched."},"paidAt":{"anyOf":[{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."}},"required":["id","companyId","status","supplierName","supplierIban","invoiceNumber","totalAmount","vatAmount","currency","invoiceDate","dueDate","paymentReference","matchedTransactionId","paidAt","createdAt","updatedAt"],"description":"A payable invoice in the bill-pay inbox, with the fields Paygoro extracted from the document."}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass as `cursor` to fetch the next page. `null` when this is the last page."}},"required":["data","nextCursor"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"BAD_REQUEST"},"status":{"const":400},"message":{"type":"string","default":"The request was malformed or failed validation."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"UNAUTHORIZED"},"status":{"const":401},"message":{"type":"string","default":"Missing, malformed, expired or revoked API key."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"status":{"const":403},"message":{"type":"string","default":"The API key does not have the scope this operation requires."},"data":{"type":"object","properties":{"requiredScopes":{"type":"array","items":{"type":"string"}}},"required":["requiredScopes"]}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"status":{"const":404},"message":{"type":"string","default":"No resource with this id exists in your workspace, or a `companyId` filter does not match one of your companies."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"429":{"description":"429","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"TOO_MANY_REQUESTS"},"status":{"const":429},"message":{"type":"string","default":"Rate limit exceeded. Retry after the `Retry-After` header."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}}},"security":[{"apiKey":["bills:read"]}],"x-required-scopes":["bills:read"]}},"/bills/{id}":{"get":{"operationId":"getBill","summary":"Get a bill","tags":["Bills"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"description":"Opaque resource id."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Opaque resource id."},"companyId":{"type":"string","minLength":1,"description":"Opaque resource id."},"status":{"enum":["new","processing","extract_failed","pending_match","matched","pending_approval","approved","scheduled","paid","rejected","archived"],"type":"string"},"supplierName":{"anyOf":[{"type":"string"},{"type":"null"}]},"supplierIban":{"anyOf":[{"type":"string"},{"type":"null"}]},"invoiceNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"totalAmount":{"anyOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","description":"Decimal amount as a string, e.g. \"1250.00\". Never a float."},{"type":"null"}]},"vatAmount":{"anyOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","description":"Decimal amount as a string, e.g. \"1250.00\". Never a float."},{"type":"null"}]},"currency":{"anyOf":[{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code, e.g. EUR."},{"type":"null"}]},"invoiceDate":{"anyOf":[{"type":"string","format":"date","description":"Calendar date in YYYY-MM-DD format."},{"type":"null"}]},"dueDate":{"anyOf":[{"type":"string","format":"date","description":"Calendar date in YYYY-MM-DD format."},{"type":"null"}]},"paymentReference":{"anyOf":[{"type":"string"},{"type":"null"}]},"matchedTransactionId":{"anyOf":[{"type":"string","minLength":1,"description":"Opaque resource id."},{"type":"null"}],"description":"The transaction that settled this bill, once matched."},"paidAt":{"anyOf":[{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."}},"required":["id","companyId","status","supplierName","supplierIban","invoiceNumber","totalAmount","vatAmount","currency","invoiceDate","dueDate","paymentReference","matchedTransactionId","paidAt","createdAt","updatedAt"],"description":"A payable invoice in the bill-pay inbox, with the fields Paygoro extracted from the document."}}}},"400":{"description":"400","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"BAD_REQUEST"},"status":{"const":400},"message":{"type":"string","default":"The request was malformed or failed validation."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"UNAUTHORIZED"},"status":{"const":401},"message":{"type":"string","default":"Missing, malformed, expired or revoked API key."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"status":{"const":403},"message":{"type":"string","default":"The API key does not have the scope this operation requires."},"data":{"type":"object","properties":{"requiredScopes":{"type":"array","items":{"type":"string"}}},"required":["requiredScopes"]}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"status":{"const":404},"message":{"type":"string","default":"No resource with this id exists in your workspace, or a `companyId` filter does not match one of your companies."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"429":{"description":"429","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"TOO_MANY_REQUESTS"},"status":{"const":429},"message":{"type":"string","default":"Rate limit exceeded. Retry after the `Retry-After` header."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}}},"security":[{"apiKey":["bills:read"]}],"x-required-scopes":["bills:read"]}},"/payees":{"get":{"operationId":"listPayees","summary":"List payees","description":"Lists saved beneficiaries, alphabetically by name.","tags":["Payees"],"parameters":[{"name":"companyId","in":"query","schema":{"type":"string","minLength":1,"description":"Restrict to one legal entity. Omit to include every entity in the workspace."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Opaque resource id."},"companyId":{"type":"string","minLength":1,"description":"Opaque resource id."},"name":{"type":"string","minLength":1,"maxLength":70},"iban":{"type":"string","description":"Normalized IBAN (uppercase, no spaces)."},"defaultReference":{"anyOf":[{"type":"string","pattern":"^[a-zA-Z0-9\\-?.+,/':() ]{1,35}$","description":"Default SEPA remittance reference (1–35 characters from the SEPA character set)."},{"type":"null"}]},"lastUsedAt":{"anyOf":[{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."},{"type":"null"}],"description":"When a transfer to this payee was last initiated."},"createdAt":{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."}},"required":["id","companyId","name","iban","defaultReference","lastUsedAt","createdAt","updatedAt"],"description":"A saved beneficiary the company pays."}}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"BAD_REQUEST"},"status":{"const":400},"message":{"type":"string","default":"The request was malformed or failed validation."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"UNAUTHORIZED"},"status":{"const":401},"message":{"type":"string","default":"Missing, malformed, expired or revoked API key."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"status":{"const":403},"message":{"type":"string","default":"The API key does not have the scope this operation requires."},"data":{"type":"object","properties":{"requiredScopes":{"type":"array","items":{"type":"string"}}},"required":["requiredScopes"]}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"status":{"const":404},"message":{"type":"string","default":"No resource with this id exists in your workspace, or a `companyId` filter does not match one of your companies."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"429":{"description":"429","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"TOO_MANY_REQUESTS"},"status":{"const":429},"message":{"type":"string","default":"Rate limit exceeded. Retry after the `Retry-After` header."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}}},"security":[{"apiKey":["payees:read"]}],"x-required-scopes":["payees:read"]},"post":{"operationId":"createPayee","summary":"Create a payee","description":"Saves a beneficiary. The IBAN is checksum-validated and normalized; one payee per IBAN per company.","tags":["Payees"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"companyId":{"type":"string","minLength":1,"description":"Required when the workspace has more than one legal entity."},"name":{"type":"string","minLength":1,"maxLength":70},"iban":{"type":"string","minLength":15,"maxLength":42,"description":"Any formatting; validated and normalized server-side."},"defaultReference":{"type":"string","pattern":"^[a-zA-Z0-9\\-?.+,/':() ]{1,35}$","description":"Default SEPA remittance reference (1–35 characters from the SEPA character set)."}},"required":["name","iban"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Opaque resource id."},"companyId":{"type":"string","minLength":1,"description":"Opaque resource id."},"name":{"type":"string","minLength":1,"maxLength":70},"iban":{"type":"string","description":"Normalized IBAN (uppercase, no spaces)."},"defaultReference":{"anyOf":[{"type":"string","pattern":"^[a-zA-Z0-9\\-?.+,/':() ]{1,35}$","description":"Default SEPA remittance reference (1–35 characters from the SEPA character set)."},{"type":"null"}]},"lastUsedAt":{"anyOf":[{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."},{"type":"null"}],"description":"When a transfer to this payee was last initiated."},"createdAt":{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."}},"required":["id","companyId","name","iban","defaultReference","lastUsedAt","createdAt","updatedAt"],"description":"A saved beneficiary the company pays."}}}},"400":{"description":"400","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"BAD_REQUEST"},"status":{"const":400},"message":{"type":"string","default":"The request was malformed or failed validation."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"UNAUTHORIZED"},"status":{"const":401},"message":{"type":"string","default":"Missing, malformed, expired or revoked API key."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"status":{"const":403},"message":{"type":"string","default":"The API key does not have the scope this operation requires."},"data":{"type":"object","properties":{"requiredScopes":{"type":"array","items":{"type":"string"}}},"required":["requiredScopes"]}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"status":{"const":404},"message":{"type":"string","default":"No resource with this id exists in your workspace, or a `companyId` filter does not match one of your companies."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"CONFLICT"},"status":{"const":409},"message":{"type":"string","default":"A payee with this IBAN already exists for the company."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"429":{"description":"429","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"TOO_MANY_REQUESTS"},"status":{"const":429},"message":{"type":"string","default":"Rate limit exceeded. Retry after the `Retry-After` header."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}}},"security":[{"apiKey":["payees:write"]}],"x-required-scopes":["payees:write"]}},"/payees/{id}":{"get":{"operationId":"getPayee","summary":"Get a payee","tags":["Payees"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"description":"Opaque resource id."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Opaque resource id."},"companyId":{"type":"string","minLength":1,"description":"Opaque resource id."},"name":{"type":"string","minLength":1,"maxLength":70},"iban":{"type":"string","description":"Normalized IBAN (uppercase, no spaces)."},"defaultReference":{"anyOf":[{"type":"string","pattern":"^[a-zA-Z0-9\\-?.+,/':() ]{1,35}$","description":"Default SEPA remittance reference (1–35 characters from the SEPA character set)."},{"type":"null"}]},"lastUsedAt":{"anyOf":[{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."},{"type":"null"}],"description":"When a transfer to this payee was last initiated."},"createdAt":{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."}},"required":["id","companyId","name","iban","defaultReference","lastUsedAt","createdAt","updatedAt"],"description":"A saved beneficiary the company pays."}}}},"400":{"description":"400","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"BAD_REQUEST"},"status":{"const":400},"message":{"type":"string","default":"The request was malformed or failed validation."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"UNAUTHORIZED"},"status":{"const":401},"message":{"type":"string","default":"Missing, malformed, expired or revoked API key."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"status":{"const":403},"message":{"type":"string","default":"The API key does not have the scope this operation requires."},"data":{"type":"object","properties":{"requiredScopes":{"type":"array","items":{"type":"string"}}},"required":["requiredScopes"]}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"status":{"const":404},"message":{"type":"string","default":"No resource with this id exists in your workspace, or a `companyId` filter does not match one of your companies."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"429":{"description":"429","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"TOO_MANY_REQUESTS"},"status":{"const":429},"message":{"type":"string","default":"Rate limit exceeded. Retry after the `Retry-After` header."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}}},"security":[{"apiKey":["payees:read"]}],"x-required-scopes":["payees:read"]},"patch":{"operationId":"updatePayee","summary":"Update a payee","description":"Updates the given fields. Transfers already made keep the beneficiary details they were sent with.","tags":["Payees"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"description":"Opaque resource id."}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":70},"iban":{"type":"string","minLength":15,"maxLength":42},"defaultReference":{"anyOf":[{"type":"string","pattern":"^[a-zA-Z0-9\\-?.+,/':() ]{1,35}$","description":"Default SEPA remittance reference (1–35 characters from the SEPA character set)."},{"type":"null"}],"description":"Set to null to clear."}},"required":[]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Opaque resource id."},"companyId":{"type":"string","minLength":1,"description":"Opaque resource id."},"name":{"type":"string","minLength":1,"maxLength":70},"iban":{"type":"string","description":"Normalized IBAN (uppercase, no spaces)."},"defaultReference":{"anyOf":[{"type":"string","pattern":"^[a-zA-Z0-9\\-?.+,/':() ]{1,35}$","description":"Default SEPA remittance reference (1–35 characters from the SEPA character set)."},{"type":"null"}]},"lastUsedAt":{"anyOf":[{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."},{"type":"null"}],"description":"When a transfer to this payee was last initiated."},"createdAt":{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp in RFC 3339 format (UTC)."}},"required":["id","companyId","name","iban","defaultReference","lastUsedAt","createdAt","updatedAt"],"description":"A saved beneficiary the company pays."}}}},"400":{"description":"400","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"BAD_REQUEST"},"status":{"const":400},"message":{"type":"string","default":"The request was malformed or failed validation."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"UNAUTHORIZED"},"status":{"const":401},"message":{"type":"string","default":"Missing, malformed, expired or revoked API key."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"status":{"const":403},"message":{"type":"string","default":"The API key does not have the scope this operation requires."},"data":{"type":"object","properties":{"requiredScopes":{"type":"array","items":{"type":"string"}}},"required":["requiredScopes"]}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"status":{"const":404},"message":{"type":"string","default":"No resource with this id exists in your workspace, or a `companyId` filter does not match one of your companies."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"CONFLICT"},"status":{"const":409},"message":{"type":"string","default":"A payee with this IBAN already exists for the company."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"429":{"description":"429","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"TOO_MANY_REQUESTS"},"status":{"const":429},"message":{"type":"string","default":"Rate limit exceeded. Retry after the `Retry-After` header."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}}},"security":[{"apiKey":["payees:write"]}],"x-required-scopes":["payees:write"]},"delete":{"operationId":"deletePayee","summary":"Delete a payee","tags":["Payees"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"description":"Opaque resource id."}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Opaque resource id."},"deleted":{"const":true}},"required":["id","deleted"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"BAD_REQUEST"},"status":{"const":400},"message":{"type":"string","default":"The request was malformed or failed validation."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"UNAUTHORIZED"},"status":{"const":401},"message":{"type":"string","default":"Missing, malformed, expired or revoked API key."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"status":{"const":403},"message":{"type":"string","default":"The API key does not have the scope this operation requires."},"data":{"type":"object","properties":{"requiredScopes":{"type":"array","items":{"type":"string"}}},"required":["requiredScopes"]}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"status":{"const":404},"message":{"type":"string","default":"No resource with this id exists in your workspace, or a `companyId` filter does not match one of your companies."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}},"429":{"description":"429","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"defined":{"const":true},"code":{"const":"TOO_MANY_REQUESTS"},"status":{"const":429},"message":{"type":"string","default":"Rate limit exceeded. Retry after the `Retry-After` header."},"data":{}},"required":["defined","code","status","message"]},{"type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"status":{"type":"number"},"message":{"type":"string"},"data":{}},"required":["defined","code","status","message"]}]}}}}},"security":[{"apiKey":["payees:write"]}],"x-required-scopes":["payees:write"]}}}}