> ## 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.

# Get KYC By Document

> This data can be used in the "kyc-proof-url" of a KYC. If no document is found for this cpf/cnpj, the request will return an empty array. If a KYC with the provided document exists, only the most recent KYC record for that document will be returned. When you provide a cpf or cnpj, you will be informed.

# Get KYC By Document

This data can be used in the "kyc-proof-url" of a KYC. If no document is found for this cpf/cnpj, the request will return an empty array. If a KYC with the provided document exists, only the most recent KYC record for that document will be returned. When you provide a cpf or cnpj, you will be informed.

## Path Parameters

<ParamField path="cpf_or_cnpj" type="string" required>
  CPF or CNPJ document number
</ParamField>

## Body

<ParamField body="document" type="string" required>
  Provide either a CPF or CNPJ number (digits only, no special characters)
</ParamField>

## Response

<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 `PAYOUT`
</ResponseField>

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

<ResponseField name="info_add" type="string">
  Additional information.
</ResponseField>

<ResponseField name="created_at" type="string">
  Date and time when 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">
  Name 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="reason" type="object">
  Object representing the reason for the KYC request.

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

    <ResponseField name="name" type="string">
      Name or description of the reason.

      Example: `Payout: Limit BRL 100K Usual`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="persons" type="array">
  List of people or entities involved in the KYC process.

  <Expandable title="Person Object">
    <ResponseField name="id" type="integer">
      Unique identifier of the person.
    </ResponseField>

    <ResponseField name="name" type="string">
      Common or display name of the person.
    </ResponseField>

    <ResponseField name="legal_name" type="string">
      Legal name.
    </ResponseField>

    <ResponseField name="document" type="string">
      Document number.
    </ResponseField>

    <ResponseField name="type_person" type="string">
      Type of person.

      Example: `Beneficiary`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="document_required" type="array">
  List of required document types for this person.

  <Expandable title="Document Required Object">
    <ResponseField name="status" type="boolean">
      Indicates whether this document is required for the KYC process.
    </ResponseField>

    <ResponseField name="label" type="string">
      Display label for the required document.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="documents" type="array">
  List of uploaded documents related to the KYC.

  <Expandable title="Document Object">
    <ResponseField name="id" type="integer">
      Unique identifier of the uploaded document.
    </ResponseField>

    <ResponseField name="status_id" type="integer">
      Current validation status ID.
    </ResponseField>

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

    <ResponseField name="document_id" type="integer">
      ID of the uploaded document.
    </ResponseField>

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

    <ResponseField name="collection_name" type="string">
      Name of the document collection or group, if applicable.
    </ResponseField>

    <ResponseField name="collection_id" type="integer">
      Identifier of the document collection.
    </ResponseField>

    <ResponseField name="value_field" type="string">
      URL for downloading the uploaded document file.
    </ResponseField>

    <ResponseField name="rejection_reason" type="string">
      Reason for rejection if the document was not approved.
    </ResponseField>

    <ResponseField name="label" type="string">
      Label or description used to identify the document field.
    </ResponseField>

    <ResponseField name="type_field" type="string">
      Input type.

      Example: `file` or `text`
    </ResponseField>

    <ResponseField name="required_field" type="boolean">
      Whether this document is required for KYC completion.
    </ResponseField>

    <ResponseField name="expires_at" type="string">
      Expiration date of the document.
    </ResponseField>

    <ResponseField name="automaticatic_validation" type="integer">
      Indicates if the document supports automatic validation.

      Example: `1` = yes, `0` = no
    </ResponseField>
  </Expandable>
</ResponseField>

## Request Example

<CodeGroup>
  ```bash cURL - CPF theme={null}
  curl --request POST \
    --url 'https://api.sandbox.wepayout.com.br/v1/kyc/document/12345678900' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer 123' \
    --header 'Content-Type: application/json' \
    --data '{
      "document": "12345678901"
    }'
  ```

  ```bash cURL - CNPJ theme={null}
  curl --request POST \
    --url 'https://api.sandbox.wepayout.com.br/v1/kyc/document/12345678000190' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer 123' \
    --header 'Content-Type: application/json' \
    --data '{
      "document": "12345678000190"
    }'
  ```

  ```javascript JavaScript theme={null}
  async function getKYCByDocument(document) {
    const response = await fetch(
      `https://api.sandbox.wepayout.com.br/v1/kyc/document/${document}`,
      {
        method: 'POST',
        headers: {
          'Accept': 'application/json',
          'Authorization': 'Bearer 123',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          document: document
        })
      }
    );
    
    if (!response.ok) {
      throw new Error(`Failed to fetch KYC: ${response.statusText}`);
    }
    
    return await response.json();
  }

  // Usage - CPF
  const kycByCPF = await getKYCByDocument('12345678900');
  console.log('KYC by CPF:', kycByCPF);

  // Usage - CNPJ
  const kycByCNPJ = await getKYCByDocument('12345678000190');
  console.log('KYC by CNPJ:', kycByCNPJ);
  ```

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

  def get_kyc_by_document(document):
      url = f'https://api.sandbox.wepayout.com.br/v1/kyc/document/{document}'
      headers = {
          'Accept': 'application/json',
          'Authorization': 'Bearer 123',
          'Content-Type': 'application/json'
      }
      
      data = {
          'document': document
      }
      
      response = requests.post(url, headers=headers, json=data)
      response.raise_for_status()
      
      return response.json()

  # Usage - CPF
  kyc_by_cpf = get_kyc_by_document('12345678900')
  print('KYC by CPF:', kyc_by_cpf)

  # Usage - CNPJ
  kyc_by_cnpj = get_kyc_by_document('12345678000190')
  print('KYC by CNPJ:', kyc_by_cnpj)
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "id": 348,
    "origin_request": "PAYOUT",
    "description": " Compliance approved KYC without document upload",
    "info_add": null,
    "created_at": "2022-06-14 17:15:41",
    "updated_at": "2023-10-03 16:01:28",
    "merchant": "Merchant Name",
    "submerchant": null,
    "status": {
      "id": 3,
      "name": "Approved"
    },
    "reason": {
      "id": 17,
      "name": "Payout: Limit BRL 100K Usual"
    },
    "persons": [
      {
        "id": 390,
        "name": "Person name",
        "legal_name": null,
        "document": "83562580061",
        "type_person": "Beneficiary"
      }
    ],
    "document_required": [
      {
        "status": true,
        "label": "Document proving the origin and destination of the operation"
      },
      {
        "status": true,
        "label": "Proof of residence"
      },
      {
        "status": true,
        "label": "Personal document"
      },
      {
        "status": true,
        "label": "Beneficiary Full Name"
      },
      {
        "status": true,
        "label": "Email"
      },
      {
        "status": true,
        "label": "Phone"
      },
      {
        "status": true,
        "label": "Nationality"
      },
      {
        "status": true,
        "label": "Profession (Occupation)"
      }
    ],
    "documents": [
      {
        "id": 652,
        "status_id": 3,
        "status_name": "Approved",
        "document_id": 1,
        "document_name": "invoice",
        "collection_name": null,
        "collection_id": null,
        "value_field": "https://bucket-name.s3.us-east-1.amazonaws.com/path/to/file",
        "rejection_reason": null,
        "label": "Document proving the origin and destination of the operation",
        "type_field": "file",
        "required_field": true,
        "expires_at": null,
        "automaticatic_validation": 0
      },
      {
        "id": 653,
        "status_id": 3,
        "status_name": "Approved",
        "document_id": 2,
        "document_name": "address",
        "collection_name": null,
        "collection_id": null,
        "value_field": "https://bucket-name.s3.us-east-1.amazonaws.com/path/to/file",
        "rejection_reason": null,
        "label": "Proof of residence",
        "type_field": "file",
        "required_field": true,
        "expires_at": null,
        "automaticatic_validation": 0
      },
      {
        "id": 654,
        "status_id": 3,
        "status_name": "Approved",
        "document_id": 3,
        "document_name": "personal-document",
        "collection_name": null,
        "collection_id": null,
        "value_field": "https://bucket-name.s3.us-east-1.amazonaws.com/path/to/file",
        "rejection_reason": null,
        "label": "Personal document",
        "type_field": "file",
        "required_field": true,
        "expires_at": null,
        "automaticatic_validation": 0
      },
      {
        "id": 655,
        "status_id": 3,
        "status_name": "Approved",
        "document_id": 5,
        "document_name": "full-name-beneficiary",
        "collection_name": null,
        "collection_id": null,
        "value_field": null,
        "rejection_reason": null,
        "label": "Beneficiary Full Name",
        "type_field": "text",
        "required_field": true,
        "expires_at": null,
        "automaticatic_validation": 0
      },
      {
        "id": 656,
        "status_id": 3,
        "status_name": "Approved",
        "document_id": 7,
        "document_name": "email",
        "collection_name": null,
        "collection_id": null,
        "value_field": null,
        "rejection_reason": null,
        "label": "Email",
        "type_field": "text",
        "required_field": true,
        "expires_at": null,
        "automaticatic_validation": 0
      },
      {
        "id": 657,
        "status_id": 3,
        "status_name": "Approved",
        "document_id": 8,
        "document_name": "phone",
        "collection_name": null,
        "collection_id": null,
        "value_field": null,
        "rejection_reason": null,
        "label": "Phone",
        "type_field": "text",
        "required_field": true,
        "expires_at": null,
        "automaticatic_validation": 0
      },
      {
        "id": 658,
        "status_id": 3,
        "status_name": "Approved",
        "document_id": 11,
        "document_name": "nationality",
        "collection_name": null,
        "collection_id": null,
        "value_field": null,
        "rejection_reason": null,
        "label": "Nationality",
        "type_field": "text",
        "required_field": true,
        "expires_at": null,
        "automaticatic_validation": 0
      },
      {
        "id": 659,
        "status_id": 3,
        "status_name": "Approved",
        "document_id": 9,
        "document_name": "profession",
        "collection_name": null,
        "collection_id": null,
        "value_field": null,
        "rejection_reason": null,
        "label": "Profession (Occupation)",
        "type_field": "text",
        "required_field": true,
        "expires_at": null,
        "automaticatic_validation": 0
      }
    ]
  }
  ```

  ```json 200 OK - Empty Array theme={null}
  []
  ```

  ```json 404 Not Found theme={null}
  {
    "message": "Not found"
  }
  ```
</ResponseExample>

## Use Cases

<AccordionGroup>
  <Accordion title="Search KYC by Document">
    Retrieve KYC information using a CPF or CNPJ document:

    ```javascript theme={null}
    async function searchByDocument(document) {
      try {
        const kyc = await getKYCByDocument(document);
        
        if (Array.isArray(kyc) && kyc.length === 0) {
          console.log('No KYC found for this document');
          return null;
        }
        
        const person = kyc.persons[0];
        console.log(`Found KYC for ${person.name}`);
        console.log(`Document: ${person.document}`);
        console.log(`Status: ${kyc.status.name}`);
        console.log(`Reason: ${kyc.reason.name}`);
        
        return kyc;
      } catch (error) {
        console.error('Error searching KYC:', error);
      }
    }
    ```
  </Accordion>

  <Accordion title="Check Document Status">
    Check the status and documents for a specific document number:

    ```javascript theme={null}
    async function checkDocumentStatus(document) {
      try {
        const kyc = await getKYCByDocument(document);
        
        if (Array.isArray(kyc) && kyc.length === 0) {
          return { found: false };
        }
        
        const approvedDocs = kyc.documents.filter(doc => doc.status_id === 3);
        
        return {
          found: true,
          status: kyc.status.name,
          totalDocuments: kyc.documents.length,
          approvedDocuments: approvedDocs.length,
          persons: kyc.persons.map(p => p.name)
        };
      } catch (error) {
        console.error('Error checking document status:', error);
      }
    }
    ```
  </Accordion>

  <Accordion title="Validate Document Before Transaction">
    Check if a document has an approved KYC before processing a transaction:

    ```javascript theme={null}
    async function validateDocumentForTransaction(document) {
      const kyc = await getKYCByDocument(document);
      
      if (Array.isArray(kyc) && kyc.length === 0) {
        return {
          valid: false,
          reason: 'No KYC record found'
        };
      }
      
      const isApproved = kyc.status.id === 3;
      
      return {
        valid: isApproved,
        kycId: kyc.id,
        status: kyc.status.name,
        reason: isApproved ? 'KYC approved' : `KYC status: ${kyc.status.name}`
      };
    }

    // Usage
    const validation = await validateDocumentForTransaction('12345678900');
    if (validation.valid) {
      console.log('Document validated, proceed with transaction');
    } else {
      console.log(`Cannot proceed: ${validation.reason}`);
    }
    ```
  </Accordion>

  <Accordion title="Get Most Recent KYC">
    Since this endpoint returns only the most recent KYC, use it to check current status:

    ```javascript theme={null}
    async function getMostRecentKYC(document) {
      const kyc = await getKYCByDocument(document);
      
      if (Array.isArray(kyc) && kyc.length === 0) {
        return null;
      }
      
      const person = kyc.persons[0];
      
      return {
        id: kyc.id,
        person: person.name,
        document: person.document,
        personType: person.type_person,
        status: kyc.status.name,
        reason: kyc.reason.name,
        lastUpdate: kyc.updated_at,
        createdAt: kyc.created_at
      };
    }
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

<Note>
  **Document Format**: Send only digits in the document field, without special characters like dots, hyphens, or slashes.
</Note>

<Warning>
  **Most Recent Record**: This endpoint returns only the most recent KYC record for the provided document. If you need historical records, use the List KYC endpoint.
</Warning>

<Tip>
  **Empty Array**: An empty array response indicates no KYC record exists for the provided document, which is different from a 404 error.
</Tip>

## Related Resources

<CardGroup cols={2}>
  <Card title="List KYC" icon="list" href="/api-reference/kyc/list-kyc">
    List all KYC verifications
  </Card>

  <Card title="Get KYC By ID" icon="magnifying-glass" href="/api-reference/kyc/get">
    Get KYC by ID
  </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>
</CardGroup>