Approvals & Requests 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

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

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

See Application Scopes for how scopes are granted and validated.

Request Types

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 Webhooks for setup and verification.

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