> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # List an organization's policy requests > Lists the organization's policy requests — the approval requests opened when a business policy requires approval for a payment, a transfer request or a reviewed transaction. Organization admins see every request of the organization, and can narrow the list to one user with `userId`. Any other member sees only the requests they created or take part in approving: without `userId` the list is theirs, and naming another user is refused with `403`. Filter by `requestStatus`, `executionStatus`, `subjectType` or `subjectId`, or search with `query`. `approvalStatus` narrows to the requests with an approval step in that status that names the `userId` user — `?userId=&approvalStatus=REQUESTED` lists the requests waiting for that user's decision — and is refused without `userId`. It looks at the step, not at the user's own decision: a group step another member approved is `APPROVED` for every member. The list is sorted by `approvalDeadline`, soonest first, unless you choose another `sort`; page with `limit` + `next`. Each parameter takes one value. ## OpenAPI ````yaml /api-reference/ruleengine.openapi.json get /realms/{realmId}/organizations/{organizationId}/policy-requests openapi: 3.0.3 info: title: Ruleengine version: 1.0.0 description: >- Portão 3 ruleengine API. Every endpoint requires a bearer token in the Authorization header (Authorization: Bearer ) unless its page states otherwise; see the Authentication guide. That requirement is not repeated per endpoint. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Confidence tiers: generated:typed=23 copied:manual=0 unknown=0. servers: - url: https://api.ruleengine.v2.portao3.com.br/ description: production - url: https://api.ruleengine.dev.3pers.com.br/ description: development security: [] tags: - name: Business Policies - name: Policy Requests paths: /realms/{realmId}/organizations/{organizationId}/policy-requests: get: tags: - Policy Requests summary: List an organization's policy requests description: >- Lists the organization's policy requests — the approval requests opened when a business policy requires approval for a payment, a transfer request or a reviewed transaction. operationId: getRealmsByRealmIdOrganizationsByOrganizationIdPolicyRequests parameters: - name: realmId in: path required: true description: |- ID of your realm. Format: `UUID` schema: type: string format: uuid example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b - name: organizationId in: path required: true description: |- ID of the organization whose policy requests you want to list. Format: `UUID` schema: type: string format: uuid example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 - name: query in: query required: false description: >- Only requests whose wallet name, requester name or e-mail, or recipient name contains this text (case-insensitive). schema: type: string minLength: 1 maxLength: 120 example: Gráfica Aurora - name: userId in: query required: false description: >- Only requests this user created or takes part in approving. Organization admins can name any user, or omit it to list the whole organization; any other member only sees their own requests — omitted means themselves, and naming someone else is refused. schema: type: string minLength: 1 example: 0b6f2c1e-8d4a-4f3b-9a7e-5c2d1e0f9a8b - name: requestStatus in: query required: false description: Only requests in this status. schema: type: string enum: - REQUESTED - APPROVED - DENIED - CANCELED - EXPIRED example: REQUESTED - name: executionStatus in: query required: false description: >- Only requests whose execution — what happens after the approval — is in this status. schema: type: string enum: - WAITING - PROCESSING - EXECUTED - FAILED example: EXECUTED - name: approvalStatus in: query required: false description: >- Only requests with an approval step in this status that names the user in `userId` — `REQUESTED` lists the ones waiting for their decision. It is the step's status, not the user's own decision. Requires `userId`. schema: type: string enum: - WAITING - REQUESTED - APPROVED - DENIED - CANCELED example: REQUESTED - name: subjectType in: query required: false description: >- Only requests for this kind of subject: `PIX`, `BOLETO`, `WALLET_TRANSFER_REQUEST` or `TRANSACTION` (a spend review). schema: type: string minLength: 1 example: PIX - name: subjectId in: query required: false description: >- Only requests for this subject — the ID of the payment, transfer request or transaction. schema: type: string minLength: 1 example: 6726a4f1b4d3e80012c9a3f1 - name: sort in: query required: false description: Field to sort by. Defaults to `approvalDeadline`, soonest first. schema: type: string enum: - approvalDeadline - createdAt - requester.name example: createdAt - name: direction in: query required: false description: >- Sort direction. Defaults to `asc` for `approvalDeadline` and `requester.name`, and to `desc` (newest first) for `createdAt`. schema: type: string enum: - asc - desc example: desc - name: next in: query required: false description: >- Cursor returned as `next` by the previous page. Omit for the first page. schema: type: string minLength: 1 example: MjAyNi0xMS0wNlQyMTowMDowMC4wMDBa - name: limit in: query required: false description: Page size. Defaults to 20. schema: type: integer minimum: 0 exclusiveMinimum: true maximum: 100 example: 20 responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string description: ID of the policy request. example: 4d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a format: uuid realmId: type: string description: ID of the realm the request belongs to. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organizationId: type: string description: ID of the organization the request belongs to. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 format: uuid accountId: type: string description: ID of the account that holds `walletId`. example: 66f2a1c7b4d3e80012c9a0b4 walletId: type: string description: >- ID of the subject's wallet — the paying wallet of a payment, the transaction's wallet in a spend review. example: 6710b8e4c9e77b0012a4d6f3 walletName: type: string description: >- Name of the wallet when the request was opened. Absent on older requests. example: Marketing cardName: type: string description: >- Name of the card, for a reviewed card transaction. Absent otherwise. example: Cartão Marketing context: type: string enum: - PAYMENT - SPEND_REVIEW - TRAVEL description: >- Which policies govern the subject: `PAYMENT`, `SPEND_REVIEW` or `TRAVEL`. example: PAYMENT subjectType: type: string description: >- What is being approved: `PIX`, `BOLETO`, `WALLET_TRANSFER_REQUEST` (a transfer request between wallets) or `TRANSACTION` (a spend review). example: PIX subjectId: type: string description: >- ID of the subject — the payment's `_id`, the transfer request's or the transaction's ID. example: 6726a4f1b4d3e80012c9a3f1 requester: type: object properties: userId: type: string description: ID of the user who asked for the subject. example: 9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d name: type: string description: >- The requester's full name when the request was opened. example: Ana Souza email: type: string description: >- The requester's e-mail when the request was opened. example: ana.souza@example.com required: - userId - name - email description: Who asked for the subject. body: type: object additionalProperties: {} description: >- The subject as it was when the request was opened — what the policies evaluated and what the approvers are approving. A payment's approved amount and balance category are in `confirmation`. --- Example: `{"amount":123000,"description":"Folders da campanha de novembro","creditParty":{"name":"Gráfica Aurora Ltda"},"confirmation":{"amount":123000,"category":"FLEX_INTERNATIONAL"}}` example: amount: 123000 description: Folders da campanha de novembro creditParty: name: Gráfica Aurora Ltda confirmation: amount: 123000 category: FLEX_INTERNATIONAL policyId: type: string description: >- ID of the business policy that required the approval. example: 3f2e1d0c-9b8a-4c7d-8e6f-5a4b3c2d1e0f format: uuid status: type: string enum: - REQUESTED - APPROVED - DENIED - CANCELED - EXPIRED description: >- Status of the request. `REQUESTED` — waiting for decisions. `APPROVED` — every required approval was given (or an admin force-approved it). `DENIED` — an approver or an admin denied it. `CANCELED` — the requester, an admin or Portão 3 cancelled it. `EXPIRED` — `approvalDeadline` passed while it was waiting. Every status but `REQUESTED` is final. example: REQUESTED denialReason: type: string description: >- The reason given by whoever denied the request. Only on a `DENIED` request, and only when a reason was given. example: Fora do orçamento do trimestre resolution: type: string enum: - AUTO description: >- `AUTO` when the policy approves on its own: the request was created already `APPROVED`, with no approvers, to run the policy's top-up. Absent on a request that went through approvers. example: AUTO executionMode: type: string enum: - MOVE_BALANCE_ONLY description: >- `MOVE_BALANCE_ONLY` when only the policy's top-up runs after the approval and the subject is carried out separately. Absent otherwise. example: MOVE_BALANCE_ONLY executionStatus: type: string enum: - WAITING - PROCESSING - EXECUTED - FAILED description: >- What happens after the approval: the policy's top-up, if any, then the subject is carried out (the payment is confirmed, the transfer request confirmed, the spend review approved). `WAITING` — not started: a request that is not approved stays `WAITING`, and an approved one goes back to it while a temporary problem is retried. `PROCESSING` — running. `EXECUTED` — done. `FAILED` — stopped, with the reason in `executionFailReason`. example: WAITING executionFailReason: type: string description: >- Why the execution failed, or why it is being retried — a code such as `MOVE_BALANCE_SOURCE_MISSING` for a problem detected before any money moved, otherwise the error of the step that failed (up to 200 characters). example: MOVE_BALANCE_SOURCE_MISSING approvalDeadline: type: string description: >- When the request expires if it is still waiting for decisions. Set by whoever opened the request — for a Pix or boleto payment, 21:00 (São Paulo time) of the day the payment is for, and at least one hour after it was sent. example: '2026-11-07T00:00:00.000Z' format: date-time executionMoveBalance: type: object properties: addBalance: type: boolean description: >- `true` when the policy tops up the subject's wallet with the subject's amount, from the wallet below, before the subject is carried out. example: true fromAccountId: type: string description: ID of the account the top-up is taken from. example: 66f2a1c7b4d3e80012c9a0b4 fromWalletId: type: string description: ID of the wallet the top-up is taken from. example: 66f2a1c7b4d3e80012c9a0b9 required: - addBalance description: >- The top-up the matched policy runs after the approval. Absent when it has none. approvalHierarchy: type: boolean description: >- `true` — the approval steps open one at a time, in order. `false` — they are all open at once. example: false approvals: type: array items: type: object properties: type: type: string enum: - USER - GROUP description: >- `USER` — this one user decides. `GROUP` — any one member of the group decides for it. example: USER id: type: string description: >- ID of the user (`type: USER`) or of the group (`type: GROUP`). example: 0b6f2c1e-8d4a-4f3b-9a7e-5c2d1e0f9a8b name: type: string description: >- Name of the user or group when the request was opened. An organization admin's force-approve or force-deny adds a step of its own, named after the admin. example: Rafael Lima status: type: string enum: - WAITING - REQUESTED - APPROVED - DENIED - CANCELED description: >- Status of the step. `WAITING` — not open yet: with `approvalHierarchy`, steps open one at a time, in order. `REQUESTED` — waiting for a decision. `APPROVED` / `DENIED` — decided. `CANCELED` — no longer needed, because the request was denied, cancelled, expired or decided by an admin. example: REQUESTED users: type: array items: type: object properties: userId: type: string description: ID of the user. example: 0b6f2c1e-8d4a-4f3b-9a7e-5c2d1e0f9a8b userName: type: string description: >- The user's full name when the request was opened; empty if they had none. example: Rafael Lima userEmail: type: string description: >- The user's e-mail when the request was opened. example: rafael.lima@example.com status: type: string enum: - WAITING - REQUESTED - APPROVED - DENIED - CANCELED description: >- This user's own decision status. `REQUESTED` means their decision is awaited; `CANCELED` means they no longer need to decide — another member of the group decided first, or the request was closed. example: REQUESTED required: - userId - userName - userEmail - status description: One person who can decide an approval step. description: >- Who can decide this step — one entry for a user, one per member for a group. createdAt: type: string description: When the step was created. example: '2026-11-06T13:42:10.512Z' format: date-time requestedAt: type: string description: >- When the step opened for a decision. Absent while it is `WAITING`. example: '2026-11-06T13:42:10.512Z' format: date-time decisionAt: type: string description: When the step was decided. example: '2026-11-06T15:03:44.207Z' format: date-time decisionReason: type: string description: >- The reason the decider gave, when they gave one. example: Fora do orçamento do trimestre required: - type - id - name - status - users description: >- One approval step: a user or a group whose decision the policy requires. description: >- The approval steps, in the policy's order. Empty on an `AUTO` request. fundingClaimedAt: type: string description: >- When this request took charge of topping up the subject's wallet — just before the top-up ran. Only on the one request per subject that does it. example: '2026-11-06T15:03:45.031Z' format: date-time fundedAt: type: string description: >- When the top-up for this subject completed. Absent while it has not completed, or when this request moved no money. example: '2026-11-06T15:03:46.418Z' format: date-time fundingClaim: type: boolean description: >- `true` on the one request per subject that took charge of topping up its wallet. It is set before the top-up runs and kept even if the top-up then fails, so it does not mean the money moved — `fundedAt` does. Absent otherwise. example: true executionAttempts: type: number description: >- How many times the execution was retried after a temporary problem that happened before any money moved. Absent when it was never retried. example: 1 createdAt: type: string description: When the request was opened. example: '2026-11-06T13:42:10.512Z' format: date-time updatedAt: type: string description: When the request last changed. example: '2026-11-06T13:42:10.512Z' format: date-time required: - id - realmId - organizationId - accountId - walletId - context - subjectType - subjectId - requester - body - policyId - status - executionStatus - approvalDeadline - approvalHierarchy - approvals - createdAt - updatedAt description: >- A policy request: the approval request of a payment, a transfer request or a reviewed transaction, waiting for the decisions a business policy requires. description: The requests of this page. next: type: string nullable: true description: >- Cursor of the next page — send it as `next`. `null` on the last page. example: MjAyNi0xMS0wN1QwMDowMDowMC4wMDBa required: - items - next description: One page of policy requests. '403': description: >- `POLICY_REQUEST_FORBIDDEN` — You are not a member of the organization, or you named another user in `userId` without being an organization admin. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - POLICY_REQUEST_FORBIDDEN description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - RULE_ENGINE description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: POLICY_REQUEST_FORBIDDEN origin: RULE_ENGINE message: You do not have permission to perform this action '422': description: >- `BAD_REQUEST` — A path or query parameter is invalid — including `approvalStatus` sent without `userId`; `fields` lists each one. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BAD_REQUEST description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - RULE_ENGINE description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. fields: type: array description: >- One entry per invalid request field (validation errors only). items: type: object properties: field: type: string description: >- Path of the invalid field, e.g. `label` or `values[0].value`. example: label message: type: string description: Why the field was rejected. example: label is required code: type: string description: >- `_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`. example: LABEL_REQUIRED values: type: array items: type: string description: >- The accepted values, when the field is an enumeration. required: - field - message - code required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BAD_REQUEST origin: RULE_ENGINE message: >- Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields. fields: - field: query message: 'Too big: expected string to have <=120 characters' code: QUERY_MAX ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.