Overview - Fluz

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

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

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.
Create — Fluz creates a pending approval and assigns account managers as approvers. Your application receives an APPROVAL_CREATE webhook with the approvalId.
List (optional) — Approvers with LIST_APPROVALS can call approvalRequests to fetch open requests for the account.
Approve or decline — Approvers with MANAGE_APPROVALS call approveApprovalRequest or declineApprovalRequest. On approval, Fluz executes the requested action.
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

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

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

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

{
  "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

{
  "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).

{
  "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.

Error Handling

Request mutations return a RequestApprovalResponse:

{
  "data": {
    "requestGiftCardPurchase": {
      "success": true,
      "messageId": "1234567890"
    }
  }
}

On failure:

{
  "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).

​How It Works

​Shared Operations

​List Pending Approvals

​Approve a Request

​Decline a Request

​Application Scopes

​Request Types

​Webhooks

​APPROVAL_CREATE payload

​APPROVAL_APPROVE / APPROVAL_DECLINE payload

​APPROVAL_HANDLER_ERROR payload

​Authentication

​Error Handling