Source: https://developers.tokportal.com/account-actions/
Markdown: https://developers.tokportal.com/account-actions.md

# Account Actions

Review and provide feedback on accounts that are in the `in_review` status. You can either finalize the account to approve it, or request corrections with specific feedback.

> **WARNING: 3-day review window**
> The review window lasts **72 hours from the time the account listing enters `in_review`** (72h01 in practice). If you do not finalize the account or request corrections during that window, TokPortal automatically changes its status to `finalized`. Once finalized, the account can no longer be sent back for corrections through this review flow.
>
> The same automatic finalization applies to delivered videos, and **`auto_finalize_videos` does not switch it off**. That flag only decides whether a delivered video is approved immediately; set to `false` it gives you the review window, it does not hold work in review indefinitely. Act inside the window with `POST /bundles/:id/videos/:position/finalize` or a video corrections request.

***

## Finalize Account

Approve an account that is currently in review. This marks the account as validated and advances the bundle lifecycle.

You can call this endpoint during the 72-hour review window. Calling it is optional if no corrections are needed: an account listing that remains in `in_review` is automatically finalized after 72 hours without user review, regardless of the bundle's `auto_finalize_videos` setting.

```
POST /bundles/:id/account/finalize
```

### Requirements

- Bundle must have an account in `in_review` status.

### Example

```bash
curl -X POST https://app.tokportal.com/api/ext/bundles/bnd_abc123/account/finalize \
  -H "X-API-Key: sk_xxx"
```

### Response

```json
{
  "data": {
    "account_id": "uuid",
    "saved_account_id": "uuid",
    "bundle_id": "bnd_abc123",
    "status": "finalized"
  }
}
```

### Error Responses

| Status | Code                     | Description                           |
| ------ | ------------------------ | ------------------------------------- |
| `409`  | `ACCOUNT_INVALID_STATUS` | Account is not in `in_review` status. |
| `404`  | `BUNDLE_NOT_FOUND`       | Bundle does not exist.                |

***

## Request Corrections

Request changes to an account that is in review. Provide a general comment and specify which fields need corrections.

```
POST /bundles/:id/account/corrections
```

### Request Body

| Field     | Type   | Required | Description                                                     |
| --------- | ------ | -------- | --------------------------------------------------------------- |
| `comment` | string | Yes      | General feedback describing what needs to change.               |
| `fields`  | object | No       | Boolean flags specifying which account fields need corrections. |

### Fields Object

Each key corresponds to an account field. Set it to `true` when that field needs correction; put all human-readable instructions in `comment`.

| Field             | Type    | Description               |
| ----------------- | ------- | ------------------------- |
| `username`        | boolean | Flag the username.        |
| `visible_name`    | boolean | Flag the display name.    |
| `biography`       | boolean | Flag the biography.       |
| `profile_picture` | boolean | Flag the profile picture. |

You only need to include the fields that require corrections.

### Requirements

- Bundle must have an account in `in_review` status.
- `comment` must contain the complete correction instructions.

### Example

```bash
curl -X POST https://app.tokportal.com/api/ext/bundles/bnd_abc123/account/corrections \
  -H "X-API-Key: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Username needs to be shorter and biography should mention the city.",
    "fields": {
      "username": true,
      "biography": true
    }
  }'
```

### Response

```json
{
  "data": {
    "account_id": "uuid",
    "saved_account_id": null,
    "bundle_id": "bnd_abc123",
    "status": "pending_corrections"
  }
}
```

### Error Responses

| Status | Code                             | Description                                  |
| ------ | -------------------------------- | -------------------------------------------- |
| `400`  | `INVALID_BODY` / `INVALID_FIELD` | The comment or correction flags are invalid. |
| `409`  | `ACCOUNT_INVALID_STATUS`         | Account is not in `in_review` status.        |
| `404`  | `BUNDLE_NOT_FOUND`               | Bundle does not exist.                       |

***

## Feedback History

Each correction request is appended to the listing's internal feedback history. Fetch the bundle account to read the current public review state.

```bash
curl -X GET https://app.tokportal.com/api/ext/bundles/bnd_abc123 \
  -H "X-API-Key: sk_xxx"
```

The manager sees the full correction comment plus the exact boolean field flags. A corrected submission returns to `in_review`, where you can finalize it or request another correction.