> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.hopnow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Documents

> List the evidence linked to a virtual account group and whether each file reached the provider

This endpoint works on any account you own. [Create Virtual Account Group](/fx/api-reference/virtual-account-groups/create-group) covers who can open a group and what the account needs first.

Returns the evidence linked to this group, newest first. Use it to see what has already been supplied against the group's requirements and, through `submission_status`, whether each file reached the provider: a file that failed on the way out still appears here.

Items come from [Upload Document](/fx/api-reference/virtual-account-groups/upload-document), and each one's `requirement_key` points back at the requirement it satisfies in [Get Virtual Account Group](/fx/api-reference/virtual-account-groups/get-group), which remains the authority on what is still outstanding. Evidence imported by the provider outside this API is listed too, with `requirement_key` set to `null`.

Requires an API key with `read` access on the `virtual_accounts` scope.

## Path Parameters

<ParamField path="account_id" type="string" required>
  The account's external ID (starts with `acct_`)
</ParamField>

<ParamField path="group_id" type="string" required>
  The virtual account group's external ID (starts with `vag_`). It must belong to the account in the path.
</ParamField>

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number (minimum 1)
</ParamField>

<ParamField query="size" type="integer" default="10">
  Items per page (1-100)
</ParamField>

## Response

<ResponseField name="items" type="array">
  Document objects linked to this group, newest first. There are no sort or filter parameters

  <Expandable title="Document Fields">
    <ResponseField name="id" type="string">
      Document identifier (starts with `doc_`). Evidence is stored at account level, so the same document id can appear under more than one group.
    </ResponseField>

    <ResponseField name="object" type="string">
      Always returns `"virtual_account_group_document"`
    </ResponseField>

    <ResponseField name="account_id" type="string">
      Account the evidence belongs to (starts with `acct_`)
    </ResponseField>

    <ResponseField name="virtual_account_group_id" type="string">
      Virtual account group the evidence is linked to (starts with `vag_`)
    </ResponseField>

    <ResponseField name="requirement_key" type="string">
      Requirement this evidence satisfies, or `null` for evidence the provider imported outside this API
    </ResponseField>

    <ResponseField name="type" type="string">
      Document type, for example `passport` or `certificate_of_incorporation`. See [Upload Document](/fx/api-reference/virtual-account-groups/upload-document) for the full set.
    </ResponseField>

    <ResponseField name="side" type="string">
      `front` or `back` for a two-sided identity document, otherwise `null`
    </ResponseField>

    <ResponseField name="file_name" type="string">
      Stored file name, or `null`
    </ResponseField>

    <ResponseField name="content_type" type="string">
      Media type of the stored file: `application/pdf`, `image/jpeg` or `image/png`
    </ResponseField>

    <ResponseField name="size_bytes" type="integer">
      Size of the file in bytes
    </ResponseField>

    <ResponseField name="submission_status" type="string">
      Delivery state towards the provider: `submitted` once the provider acknowledged it, `failed` when the last delivery attempt was rejected, `pending` while it is on its way, and `unknown` for links created before delivery was tracked, including provider-imported evidence. Re-drive a `failed` file by uploading it again.
    </ResponseField>

    <ResponseField name="country_code" type="string">
      ISO 3166-1 alpha-2 country of issue, or `null`
    </ResponseField>

    <ResponseField name="created" type="string">
      ISO 8601 timestamp when created
    </ResponseField>

    <ResponseField name="updated" type="string">
      ISO 8601 timestamp when last updated
    </ResponseField>

    <ResponseField name="created_by" type="string">
      Actor that uploaded the document: the API key id (starts with `ak_`), or `null` for provider-imported evidence
    </ResponseField>

    <ResponseField name="updated_by" type="string">
      Actor that last updated the document, or `null`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="page" type="integer">
  Current page number
</ResponseField>

<ResponseField name="size" type="integer">
  Items per page
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of items
</ResponseField>

<ResponseField name="pages" type="integer">
  Total number of pages
</ResponseField>

## Errors

| Status | `code` | When |
| - | - | - |
| `404` | `RESOURCE_NOT_FOUND` | `group_id` is unknown or belongs to another account |
| `422` | `VALIDATION_ERROR` | `page` or `size` is out of range |

## Request Example

```bash theme={null}
curl "https://api.hopnow.io/v1/accounts/acct_ka44qsvpo8q3wtzuwfqf0h6u/virtual-account-groups/vag_7m2k9x4c1b6v3n8q5z0j2p7t/documents?size=10" \
  -H "X-API-Key: your_api_key" \
  -H "X-Signature: hmac_signature" \
  -H "X-Timestamp: 1234567890" \
  -H "X-Nonce: abc123"
```

## Response Example

```json theme={null}
{
  "items": [
    {
      "id": "doc_xw9rlpdt0bcr5u4f9n095lf4",
      "object": "virtual_account_group_document",
      "account_id": "acct_ka44qsvpo8q3wtzuwfqf0h6u",
      "virtual_account_group_id": "vag_7m2k9x4c1b6v3n8q5z0j2p7t",
      "requirement_key": "req_9c1f4a7b2e06d38a5f4c1b72",
      "type": "passport",
      "side": null,
      "file_name": "passport.pdf",
      "content_type": "application/pdf",
      "size_bytes": 248312,
      "submission_status": "submitted",
      "country_code": "GB",
      "created": "2026-01-16T09:20:00Z",
      "updated": "2026-01-16T09:20:00Z",
      "created_by": "ak_3f7k9m2p5r8t1v4x6z0b3n5q",
      "updated_by": null
    },
    {
      "id": "doc_zc8ierkl3h51fun10108m4zd",
      "object": "virtual_account_group_document",
      "account_id": "acct_ka44qsvpo8q3wtzuwfqf0h6u",
      "virtual_account_group_id": "vag_7m2k9x4c1b6v3n8q5z0j2p7t",
      "requirement_key": "req_2b7e1d4a9c03f68b5e1a7c94",
      "type": "national_id",
      "side": "front",
      "file_name": "director-id-front.png",
      "content_type": "image/png",
      "size_bytes": 1048576,
      "submission_status": "failed",
      "country_code": "GB",
      "created": "2026-01-16T09:14:00Z",
      "updated": "2026-01-16T09:14:00Z",
      "created_by": "ak_3f7k9m2p5r8t1v4x6z0b3n5q",
      "updated_by": null
    }
  ],
  "page": 1,
  "size": 10,
  "total": 2,
  "pages": 1
}
```