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