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

# List KYC

> Retrieves a list of pending KYC verifications

# List KYC

Retrieves a list of pending KYC verifications.

<Note>
  **Status**: You can filter KYC results by using the `status_id` query parameter at the KYC listing endpoint. Below are the available status values.
</Note>

## Status Table

| TENDER ID | STATUS NAME                 |
| --------- | --------------------------- |
| 1         | Awaiting Upload Documents   |
| 2         | Awaiting Approval Documents |
| 3         | Approved                    |
| 4         | Pending Regularization      |
| 5         | Canceled                    |

## Query Parameters

<ParamField query="page" type="string">
  The current number you wish to view.
</ParamField>

<ParamField query="per_page" type="string">
  The maximum number of items shown per page.
</ParamField>

<ParamField query="sort" type="string">
  Sort order.

  Allowed values: `0`, `1`, `2`, `3`, `4`, `5`
</ParamField>

<ParamField query="status_id" type="string">
  Status filter.

  Allowed values: `1`, `2`, `3`, `4`, `5`
</ParamField>

## Response

<ResponseField name="array" type="array">
  Array of KYC records.

  <Expandable title="KYC Object">
    <ResponseField name="id" type="integer">
      Unique identifier for the KYC record.
    </ResponseField>

    <ResponseField name="origin_request" type="string">
      Identifier or reference of the original request that triggered this KYC process.

      Example: `PAYIN or REQUEST`
    </ResponseField>

    <ResponseField name="description" type="string">
      Textual description or details about the KYC request.
    </ResponseField>

    <ResponseField name="notes" type="string">
      Additional notes or observations about the KYC request.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Date and time of the KYC record was created.

      Format: `YYYY-MM-DD HH:mm:ss`
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      Date and time of the last update made to this KYC record.

      Format: `YYYY-MM-DD HH:mm:ss`
    </ResponseField>

    <ResponseField name="merchant" type="string">
      Name of the main merchant associated with the KYC process.
    </ResponseField>

    <ResponseField name="submerchant" type="string">
      Identifier of the submerchant involved in the KYC process.
    </ResponseField>

    <ResponseField name="status" type="object">
      Object representing the current status of the KYC.

      <Expandable title="Status Object">
        <ResponseField name="id" type="integer">
          Status identifier.

          Example: `1`
        </ResponseField>

        <ResponseField name="name" type="string">
          Name of the status.

          Example: `Waiting Upload Documents`, `Waiting Approval Documents`, `Approved`, `Pending Regularization` or `Canceled`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="beneficiary" type="object">
      Object with information about the person or entity being verified.

      <Expandable title="Beneficiary Object">
        <ResponseField name="id" type="integer">
          Beneficiary identifier.
        </ResponseField>

        <ResponseField name="name" type="string">
          Name of the beneficiary.
        </ResponseField>

        <ResponseField name="document" type="string">
          Document number used for identification.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Request Example

<CodeGroup>
  ```bash cURL - All KYC theme={null}
  curl --request GET \
    --url 'https://api.sandbox.wepayout.com.br/v1/kyc' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer 123'
  ```

  ```bash cURL - Filter by Status theme={null}
  curl --request GET \
    --url 'https://api.sandbox.wepayout.com.br/v1/kyc?status_id=1' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer 123'
  ```

  ```bash cURL - With Pagination theme={null}
  curl --request GET \
    --url 'https://api.sandbox.wepayout.com.br/v1/kyc?page=1&per_page=10' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer 123'
  ```

  ```javascript JavaScript theme={null}
  async function listKYC(filters = {}) {
    const params = new URLSearchParams({
      page: filters.page || 1,
      per_page: filters.perPage || 10,
      ...filters
    });
    
    const response = await fetch(
      `https://api.sandbox.wepayout.com.br/v1/kyc?${params}`,
      {
        method: 'GET',
        headers: {
          'Accept': 'application/json',
          'Authorization': 'Bearer 123'
        }
      }
    );
    
    return await response.json();
  }

  // Usage examples
  // List all KYC records
  const allKYC = await listKYC();

  // Filter by status
  const pendingKYC = await listKYC({ status_id: 1 });

  // With pagination
  const page1 = await listKYC({ page: 1, per_page: 10 });

  console.log('KYC records:', allKYC);
  ```

  ```python Python theme={null}
  import requests

  def list_kyc(filters=None):
      url = 'https://api.sandbox.wepayout.com.br/v1/kyc'
      headers = {
          'Accept': 'application/json',
          'Authorization': 'Bearer 123'
      }
      
      params = {
          'page': 1,
          'per_page': 10
      }
      
      if filters:
          params.update(filters)
      
      response = requests.get(url, headers=headers, params=params)
      return response.json()

  # Usage examples
  # List all KYC records
  all_kyc = list_kyc()

  # Filter by status
  pending_kyc = list_kyc({'status_id': 1})

  # With pagination
  page_1 = list_kyc({'page': 1, 'per_page': 10})

  print('KYC records:', all_kyc)
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 OK theme={null}
  [
    {
      "id": 1563,
      "origin_request": "PAYIN",
      "description": "test",
      "notes": null,
      "created_at": "2025-05-19 10:53:48",
      "updated_at": "2025-05-19 10:53:48",
      "merchant": "Merchant's name",
      "submerchant": null,
      "status": {
        "id": 1,
        "name": "Waiting Upload Documents"
      },
      "beneficiary": {
        "id": 1691,
        "name": "TEST",
        "document": "12345678987"
      }
    }
  ]
  ```
</ResponseExample>

## Use Cases

<AccordionGroup>
  <Accordion title="Monitor Pending KYC Verifications">
    Track all KYC verifications that are awaiting document upload:

    ```javascript theme={null}
    async function getPendingKYC() {
      const pending = await listKYC({ status_id: 1 });
      
      console.log(`Found ${pending.length} pending KYC verifications`);
      
      pending.forEach(kyc => {
        console.log(`- ${kyc.beneficiary.name}: ${kyc.status.name}`);
      });
      
      return pending;
    }
    ```
  </Accordion>

  <Accordion title="Filter by Origin Request">
    Get KYC records by origin (PAYIN or REQUEST):

    ```javascript theme={null}
    async function getKYCByOrigin(origin) {
      const allKYC = await listKYC();
      
      return allKYC.filter(kyc => kyc.origin_request === origin);
    }

    // Get all PAYIN-related KYC
    const payinKYC = await getKYCByOrigin('PAYIN');
    ```
  </Accordion>

  <Accordion title="Track KYC Status Changes">
    Monitor KYC status changes over time:

    ```javascript theme={null}
    async function trackKYCStatus(kycId) {
      const allKYC = await listKYC();
      const kyc = allKYC.find(k => k.id === kycId);
      
      if (!kyc) {
        throw new Error('KYC not found');
      }
      
      return {
        id: kyc.id,
        beneficiary: kyc.beneficiary.name,
        currentStatus: kyc.status.name,
        lastUpdate: kyc.updated_at,
        origin: kyc.origin_request
      };
    }
    ```
  </Accordion>

  <Accordion title="Generate KYC Report">
    Generate a report of all KYC verifications by status:

    ```javascript theme={null}
    async function generateKYCReport() {
      const allKYC = await listKYC();
      
      const report = {
        total: allKYC.length,
        byStatus: {},
        byOrigin: {}
      };
      
      allKYC.forEach(kyc => {
        // Count by status
        const statusName = kyc.status.name;
        report.byStatus[statusName] = (report.byStatus[statusName] || 0) + 1;
        
        // Count by origin
        const origin = kyc.origin_request;
        report.byOrigin[origin] = (report.byOrigin[origin] || 0) + 1;
      });
      
      return report;
    }

    // Usage
    const report = await generateKYCReport();
    console.log('KYC Report:', report);
    // Output: { total: 50, byStatus: { 'Approved': 30, 'Pending': 20 }, byOrigin: { 'PAYIN': 35, 'REQUEST': 15 } }
    ```
  </Accordion>
</AccordionGroup>

## Status Workflow

```mermaid theme={null}
graph TD
    A[KYC Created] --> B[1 - Awaiting Upload Documents]
    B --> C[2 - Awaiting Approval Documents]
    C --> D{Approved?}
    D -->|Yes| E[3 - Approved]
    D -->|No| F[4 - Pending Regularization]
    F --> B
    B --> G[5 - Canceled]
    C --> G
```

## Best Practices

<Note>
  **Pagination**: Always use pagination when listing KYC records to avoid performance issues. The default page size is 10.
</Note>

<Warning>
  **Status Monitoring**: Regularly check KYC status to ensure timely document uploads and approvals.
</Warning>

<Tip>
  **Filter by Status**: Use the `status_id` parameter to filter KYC records by specific statuses and reduce response size.
</Tip>

## Related Resources

<CardGroup cols={2}>
  <Card title="Get Balance" icon="wallet" href="/api-reference/account/get-balance">
    Check account balance
  </Card>

  <Card title="Create Charge" icon="plus" href="/api-reference/cash-in/payin/create-charge">
    Create a new charge
  </Card>

  <Card title="Create Payment" icon="money-bill-transfer" href="/api-reference/cash-out/payout/create-payment">
    Create a payout payment
  </Card>

  <Card title="Get Statement" icon="file-invoice" href="/api-reference/account/get-statement">
    View account statement
  </Card>
</CardGroup>