> For the complete documentation index, see [llms.txt](https://docs.aquanow.io/aquanow/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aquanow.io/aquanow/api-endpoints-or-v1.0/transaction-api/approvals.md).

# Approvals

This feature enables users who do not have direct withdrawal permission to initiate a withdrawal request that can then be reviewed by a user with approval permission.

Approvers have the option to **approve** or **reject** a request, while users who initiate a request have the ability to only **cancel** their own request.

## Fetch approval requests

<mark style="color:blue;">`GET`</mark> `https://api.aquanow.io/accounts/v1/approval`

Fetches the approval(s) given by the query parameter. \ <mark style="color:orange;">NOTE:</mark> One of `startTime` or `approvalId` must be given as a query parameter. Query parameters can not be combined.

#### Query Parameters

| Name       | Type   | Description                                                                                                                                     |
| ---------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| startTime  | string | <p>Pagination token that can be used to query more data<br><mark style="color:orange;">NOTE:</mark> startTime must be within a 90 day range</p> |
| approvalId | string | <p><code>yyyy-mm-ddThh:mm:ss.sssZ</code><br>UTC time stamp when approval request was created</p>                                                |

{% tabs %}
{% tab title="200: OK Get approvals by approvalId" %}
Returns an [ApprovalsObject](/aquanow/data-objects-and-statuses/transaction-objects/approval-objects.md#approvalsobject).

```json
{
    "payload": {
        "transactionType": "WITHDRAW",
        "symbol": "USDT",
        "accountId": "CA1000052R",
        "address": "0xEE506212EE33ac1ac66D56e9Ea5D5866e8C7168e",
        "grossQuantity": 200,
        "accountName": "accountName1",
        "networkFee": 0.0001,
        "networkType": "eth"
    },
    "action": "WITHDRAW",
    "requestedBy": "userOne",
    "approvalId": "cba4e337-8876-46fe-9216-438a82ce7697",
    "status": "PENDING",
    "created": "2024-04-09T17:55:33.889Z",
    "username": "companyProfile",
    "reviewRecords": [],
    "entity": "Approval",
    "resource": "BALANCE",
    "approvalsGrossQuantity": 200,
    "approvalsQuantity": 199.9999,
}
```

{% endtab %}

{% tab title="200: OK Get approvals by startTime" %}
Returns an array of [ApprovalsObject](/aquanow/data-objects-and-statuses/transaction-objects/approval-objects.md#approvalsobject).

<pre class="language-json"><code class="lang-json">[
    {
        "payload": {
            "transactionType": "WITHDRAW",
            "symbol": "BTC",
            "accountId": "CA1000051R",
            "address": "bc1q8k5508tfz299v7ywxj8j4g4p9hkn6n06xndv0d",
            "quantity": 0.01,
            "accountName": "accountName1"
        },
        "action": "WITHDRAW",
        "requestedBy": "userOne",
        "approvalId": "8a927001-c744-412f-8e12-90519fc0c75f",
        "status": "APPROVED",
        "created": "2024-02-16T21:55:25.478Z",
        "username": "companyProfile",
        "reviewRecords": [
            {
                "reviewedAt": "2024-02-16T21:56:46.180Z",
                "comment": "123",
                "reviewedBy": "userTwo",
                "status": "APPROVED"
            }
        ],
        "entity": "Approval",
        "resource": "BALANCE",
        "approvalsGrossQuantity": 0.01,
        "approvalsQuantity": 0.01,
    },
<strong>    {
</strong>        "payload": {
            "transactionType": "WITHDRAW",
            "symbol": "USDT",
            "accountId": "CA1000052R",
            "address": "0xEE506212EE33ac1ac66D56e9Ea5D5866e8C7168e",
            "grossQuantity": 200,
            "accountName": "accountName1",
            "networkFee": 0.0001,
            "networkType": "eth"
        },
        "action": "WITHDRAW",
        "requestedBy": "userOne",
        "approvalId": "cba4e337-8876-46fe-9216-438a82ce7697",
        "status": "PENDING",
        "created": "2024-04-09T17:55:33.889Z",
        "username": "companyProfile",
        "reviewRecords": [],
        "entity": "Approval",
        "resource": "BALANCE",
        "approvalsGrossQuantity": 200,
        "approvalsQuantity": 199.9999,
    },
    {
        "payload": {
            "transactionType": "WITHDRAW",
            "symbol": "USDT",
            "accountId": "CA1000052R",
            "address": "0xEE506212EE33ac1ac66D56e9Ea5D5866e8C7168e",
            "quantity": 300,
            "accountName": "accountName1",
            "networkFee": 0.0001,
            "networkType": "eth"
        },
        "action": "WITHDRAW",
        "requestedBy": "userOne",
        "approvalId": "9511a211-78f4-43a1-be2c-4162f7338357",
        "status": "PENDING",
        "created": "2024-04-09T17:56:44.464Z",
        "username": "companyProfile",
        "reviewRecords": [],
        "entity": "Approval",
        "resource": "BALANCE",
        "approvalsGrossQuantity": 300,
        "approvalsQuantity": 299.9999,
    }
]
</code></pre>

{% endtab %}

{% tab title="500: Internal Server Error startTime is invalid" %}

```json
{
    "message": "Invalid KeyConditionExpression: The BETWEEN operator requires upper bound to be greater than or equal to lower bound; lower bound operand: AttributeValue: {S:2023-11-T08:00:00.000Z}, upper bound operand: AttributeValue: {S:2023-06-13T21:20:48.821Z}"
}
```

{% endtab %}

{% tab title="500: Internal Server Error starTime and approvalId are combined" %}

```json
{
    "message": "Invalid query parameters"
}
```

{% endtab %}

{% tab title="500: Internal Server Error approvalId is invalid" %}

```json
{
    "message": "Record not found"
}
```

{% endtab %}

{% tab title="400: Internal Server Error startTime exceeds 90 days" %}

```json
{
    "message": "Query time range must be within 90 days"
}
```

{% endtab %}

{% tab title="500: Internal Server Error startTime is in the future" %}

```json
{
    "message": "Query endTime must be later than startTime"
}
```

{% endtab %}

{% tab title="500: Internal Server Error No query parameter is given" %}

```json
{
    "message": "Invalid query parameters"
}
```

{% endtab %}
{% endtabs %}

## Create an approval request

<mark style="color:green;">`POST`</mark> `https://api.aquanow.io/accounts/v1/approval`

Please specify either `grossQuantity` or `quantity` inside the payload.

#### Request Body

| Name                                      | Type   | Description                                                                                                                             |
| ----------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| action<mark style="color:red;">\*</mark>  | string | `BALANCE/WITHDRAW`                                                                                                                      |
| payload<mark style="color:red;">\*</mark> | obj    | Contains an [ApprovalsPayloadObject](/aquanow/data-objects-and-statuses/transaction-objects/approval-objects.md#approvalspayloadobject) |
|                                           | String |                                                                                                                                         |

{% tabs %}
{% tab title="200: OK Create an approval request" %}
Returns an [ApprovalsObject](/aquanow/data-objects-and-statuses/transaction-objects/approval-objects.md#approvalsobject).

```json
{
    "approvalId": "6c0f9889-323a-4ad2-8041-e2dbddeeb7e8",
    "resource": "BALANCE",
    "action": "WITHDRAW",
    "payload": {
        "address": "0x80fB86611a28912a6D26D1bad078977402A324D9",
        "symbol": "USDC",
        "tag": "hi",
        "quantity": 1,
        "transactionType": "WITHDRAW",
        "networkFee": 0
    },
    "username": "alex_company",
    "requestedBy": "alex_company_ceo",
    "reviewRecords": [],
    "status": "PENDING",
    "approvalsGrossQuantity": 1,
    "approvalsQuantity": 1,
}
```

{% endtab %}

{% tab title="500: Internal Server Error Missing a required parameter" %}

```json
{
    "message": "Invalid request body"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Invalid parameter value" %}

```json
{
    "message": "Invalid request body"
}
```

{% endtab %}
{% endtabs %}

## Cancel an approval request

<mark style="color:red;">`DELETE`</mark> `https://api.aquanow.io/accounts/v1/approval`

<mark style="color:orange;">NOTE:</mark> Users can only cancel their own approval requests while the request status is `PENDING`.

#### Request Body

| Name                                         | Type   | Description                    |
| -------------------------------------------- | ------ | ------------------------------ |
| approvalId<mark style="color:red;">\*</mark> | string | approvalId of approval request |

{% tabs %}
{% tab title="200: OK Cancel an approval request" %}
Returns an [ApprovalsObject](/aquanow/data-objects-and-statuses/transaction-objects/approval-objects.md#approvalsobject).

```json
{
    "approvalId": "58d5081e-82dc-4tcw-a820-8440e4dfo9c0",
    "status": "CANCELLED"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Invalid approvalId" %}

```json
{
    "message": "Approval request is invalid to cancel"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Missing approvalId" %}

```json
{
    "message": "Invalid request body"
}
```

{% endtab %}
{% endtabs %}

## Review an approval request

<mark style="color:green;">`POST`</mark> `https://api.aquanow.io/accounts/v1/approval/review`

User with approver permissions can approve or reject an approval request while the status is `PENDING`.

#### Request Body

| Name                                         | Type   | Description                    |
| -------------------------------------------- | ------ | ------------------------------ |
| action<mark style="color:red;">\*</mark>     | string | `APPROVE` \| `REJECT`          |
| approvalId<mark style="color:red;">\*</mark> | string | approvalId of approval request |
| comment                                      | string | Comment set by reviewer        |

{% tabs %}
{% tab title="200: OK Review an approval request" %}
Returns an [ApprovalsObject](/aquanow/data-objects-and-statuses/transaction-objects/approval-objects.md#approvalsobject).

```json
{
    "approvalId": "58w5081e-82dc-49cw-a820-844oe4dfq9t4",
    "status": "APPROVED"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Invalid/missing approvalId or action" %}

```json
{
    "message": "Invalid request body"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Approval request has been reviewed" %}

```json
{
    "message": "Approval is invalid for review"
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.aquanow.io/aquanow/api-endpoints-or-v1.0/transaction-api/approvals.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.