> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

Use the Fluz API to submit approval requests for sensitive account actions, list pending requests, and approve or decline them on behalf of managers.

Approval requests are available through the Transactional Graph Service GraphQL API. When a request is submitted, Fluz creates a durable approval record and notifies configured approvers. If approved, the underlying action runs automatically (for example, purchasing a gift card or transferring funds).

## How It Works

```text theme={null}
Requester                    Manager / Approver
   |                                |
   |  1. request* mutation          |
   |------------------------------->|
   |                                |
   |  2. APPROVAL_CREATE webhook    |
   |<-------------------------------|
   |                                |
   |              3. approvalRequests query (optional)
   |              4. approveApprovalRequest or declineApprovalRequest
   |                                |
   |  5. APPROVAL_APPROVE or        |
   |     APPROVAL_DECLINE webhook   |
   |<-------------------------------|
```

1. **Request** — A user with the appropriate `REQUEST_*` scope calls a `request*` mutation. The API validates the input and queues the request. The mutation returns a `messageId`, not an `approvalId`.
2. **Create** — Fluz creates a pending approval and assigns account managers as approvers. Your application receives an `APPROVAL_CREATE` webhook with the `approvalId`.
3. **List (optional)** — Approvers with `LIST_APPROVALS` can call `approvalRequests` to fetch open requests for the account.
4. **Approve or decline** — Approvers with `MANAGE_APPROVALS` call `approveApprovalRequest` or `declineApprovalRequest`. On approval, Fluz executes the requested action.
5. **Webhook** — Your application receives `APPROVAL_APPROVE` or `APPROVAL_DECLINE`. If execution fails after approval, you may receive `APPROVAL_HANDLER_ERROR`.

> Requests are processed asynchronously. Poll `approvalRequests` or listen for webhooks to obtain the `approvalId` after submitting a request.

## Shared Operations

These operations apply to all approval request types.

### List Pending Approvals

`approvalRequests`

Returns open (`PENDING`) approval requests for the authenticated account.

**Required scope:** `LIST_APPROVALS`

```graphql theme={null}
query {
  approvalRequests {
    approvalId
    accountId
    requesterUserId
    approvalType
    approvalCode
    approvalStatus
    approversLogic
    expireDate
    createdAt
    approvers {
      approvalApproverId
      approverUserId
      role
      status
    }
  }
}
```

### Approve a Request

`approveApprovalRequest`

Approves a pending request. On success, Fluz runs the action associated with the request (for example, creating a virtual card).

**Required scope:** `MANAGE_APPROVALS`

```graphql theme={null}
mutation {
  approveApprovalRequest(approvalId: "07df5653-43a8-4532-9881-3ab5857bbe12") {
    success
    approvalId
    action
    error {
      code
      message
    }
  }
}
```

### Decline a Request

`declineApprovalRequest`

Declines a pending request. No downstream action is executed.

**Required scope:** `MANAGE_APPROVALS`

```graphql theme={null}
mutation {
  declineApprovalRequest(approvalId: "07df5653-43a8-4532-9881-3ab5857bbe12") {
    success
    approvalId
    action
    error {
      code
      message
    }
  }
}
```

## Application Scopes

Approval-related scopes must be granted at both the application level (by Fluz) and the user level (via OAuth consent or `generateUserAccessToken`).

| Scope                               | Usage                                                                                           |
| ----------------------------------- | ----------------------------------------------------------------------------------------------- |
| `LIST_APPROVALS`                    | List pending approval requests; receive `APPROVAL_CREATE` and `APPROVAL_HANDLER_ERROR` webhooks |
| `MANAGE_APPROVALS`                  | Approve or decline requests; receive `APPROVAL_APPROVE` and `APPROVAL_DECLINE` webhooks         |
| `REQUEST_VIRTUAL_CARD`              | Submit virtual card creation requests                                                           |
| `REQUEST_VIRTUAL_CARD_LIMIT_CHANGE` | Submit virtual card limit change requests                                                       |
| `REQUEST_GIFT_CARD`                 | Submit gift card purchase requests                                                              |
| `REQUEST_INTERNAL_TRANSFER`         | Submit internal spend-account transfer requests                                                 |
| `REQUEST_ACCOUNT_TRANSFER`          | Submit account-to-account transfer requests                                                     |
| `REQUEST_REIMBURSEMENT`             | Submit reimbursement requests                                                                   |

See [Authentication](/concepts/authentication) for how scopes are granted and validated.

## Request Types

| Request                   | Mutation                        | Create scope                        |
| ------------------------- | ------------------------------- | ----------------------------------- |
| Virtual card creation     | `requestVirtualCard`            | `REQUEST_VIRTUAL_CARD`              |
| Virtual card limit change | `requestVirtualCardLimitChange` | `REQUEST_VIRTUAL_CARD_LIMIT_CHANGE` |
| Gift card purchase        | `requestGiftCardPurchase`       | `REQUEST_GIFT_CARD`                 |
| Internal transfer         | `requestInternalTransfer`       | `REQUEST_INTERNAL_TRANSFER`         |
| Account transfer          | `requestAccountTransfer`        | `REQUEST_ACCOUNT_TRANSFER`          |
| Reimbursement             | `requestReimbursement`          | `REQUEST_REIMBURSEMENT`             |

Each request type has a dedicated guide with input fields, examples, and webhook identifiers.

## Webhooks

Configure webhooks in the Fluz developer portal. Approval events use the same delivery mechanism as other Fluz webhooks. See the [Developers overview](/developers) for setup and verification.

| Event                    | When it fires                                  | Webhook subscription scope |
| ------------------------ | ---------------------------------------------- | -------------------------- |
| `APPROVAL_CREATE`        | A new approval request is created              | `LIST_APPROVALS`           |
| `APPROVAL_APPROVE`       | A request is approved                          | `MANAGE_APPROVALS`         |
| `APPROVAL_DECLINE`       | A request is declined                          | `MANAGE_APPROVALS`         |
| `APPROVAL_HANDLER_ERROR` | Approval succeeded but action execution failed | `LIST_APPROVALS`           |

### APPROVAL\_CREATE payload

```json theme={null}
{
  "approvalId": "07df5653-43a8-4532-9881-3ab5857bbe12",
  "accountId": "b1155504-ad30-4b2f-873d-b8795277b128",
  "userId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "approvalType": "GIFT_CARD",
  "approvalCode": "400007",
  "approvalStatus": "PENDING",
  "createdAt": "2025-07-09T10:00:00Z"
}
```

Use `approvalType` and `approvalCode` together to identify the request type. Each per-type guide lists the values for that request.

### APPROVAL\_APPROVE / APPROVAL\_DECLINE payload

```json theme={null}
{
  "approvalId": "07df5653-43a8-4532-9881-3ab5857bbe12",
  "accountId": "b1155504-ad30-4b2f-873d-b8795277b128",
  "userId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "approvalType": "GIFT_CARD",
  "approvalCode": "400007",
  "approvalStatus": "APPROVED",
  "approvalAction": "APPROVE",
  "approverAccountId": "d4e5f6a7-b8c9-0123-def4-567890123456",
  "approverUserId": "e5f6a7b8-c9d0-1234-ef56-789012345678",
  "linkId": "f6a7b8c9-d0e1-2345-f678-901234567890",
  "attemptedAt": "2025-07-09T10:05:00Z"
}
```

For declines, `approvalAction` is `DECLINE` and `approvalStatus` is `DECLINED`.

### APPROVAL\_HANDLER\_ERROR payload

Sent when a request is approved but the downstream action fails (for example, insufficient balance at execution time).

```json theme={null}
{
  "approvalId": "07df5653-43a8-4532-9881-3ab5857bbe12",
  "accountId": "b1155504-ad30-4b2f-873d-b8795277b128",
  "userId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "approvalType": "GIFT_CARD",
  "approvalCode": "400007",
  "approvalStatus": "APPROVED",
  "approvalAction": "APPROVE",
  "failureStage": "ACTION_EXECUTION",
  "error": "Insufficient balance",
  "failedAt": "2025-07-09T10:05:01Z"
}
```

## Authentication

Approval mutations support Bearer token (user OAuth) and Basic Auth (application API key), depending on your integration pattern. The authenticated principal becomes the requester.

Use a User Access Token with the required scopes. See the [Authentication & Authorization Guide](/concepts/authentication).

## Error Handling

Request mutations return a `RequestApprovalResponse`:

```json theme={null}
{
  "data": {
    "requestGiftCardPurchase": {
      "success": true,
      "messageId": "1234567890"
    }
  }
}
```

On failure:

```json theme={null}
{
  "data": {
    "requestGiftCardPurchase": {
      "success": false,
      "messageId": null,
      "error": {
        "code": "APPROVAL_REQUEST_FAILED",
        "message": "Input validation error: ..."
      }
    }
  }
}
```

Approve and decline mutations return `success: false` with an `error` object when the action cannot be completed (for example, approval not found or already resolved).