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

# Create Data Qualification

> Register a batch of data qualification orders

You can use this endpoint to create a data qualification batch. In the data attribute you may pass a list of bank account data to be qualified. You can group your data qualification in batches using the `batch_code` field.

## Request Body

<ParamField body="merchant_id" type="integer">
  The Merchant ID. Required when you have access to more than one Merchant.
</ParamField>

<ParamField body="service_id" type="integer" required>
  The service ID. The available services can be retrieved in the endpoint [GET /v1/payout/data-qualification/services](/api-reference/data-qualification/get-services).

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

<ParamField body="data" type="array" required>
  Array of data qualification records.

  <Expandable title="Data Object">
    <ParamField body="amount" type="number">
      Amount in local currency, used in services 4 and 5 only.

      Min: `0.01`

      Max: `150000`

      Example: `1000`
    </ParamField>

    <ParamField body="custom_code" type="string" required>
      Custom code (Invoice) must be unique in our database.

      Example: `YourCustomCode`
    </ParamField>

    <ParamField body="batch_code" type="string" required>
      The code used to group data qualification processes.

      Example: `YOURAPPCODE`
    </ParamField>

    <ParamField body="notification_url" type="string">
      We will send you an HTTP POST with a Notification Object when deposit status changes.

      Example: `https://your.endpoint.to.update`
    </ParamField>

    <ParamField body="beneficiary" type="object" required>
      Beneficiary information.

      <Expandable title="Beneficiary Object">
        <ParamField body="name" type="string" required>
          Beneficiary's full name.

          Example: `The Name`
        </ParamField>

        <ParamField body="bank_code" type="string" required>
          Bank code.

          Example: `147`
        </ParamField>

        <ParamField body="bank_branch" type="string" required>
          Bank branch.

          Example: `0000`
        </ParamField>

        <ParamField body="bank_branch_digit" type="string">
          Bank branch digit.

          Example: `1`
        </ParamField>

        <ParamField body="account" type="string" required>
          Account number.

          Example: `1030000`
        </ParamField>

        <ParamField body="account_digit" type="string" required>
          Account digit.

          Example: `1`
        </ParamField>

        <ParamField body="account_type" type="string" required>
          Account type.

          Allowed values: `SAVINGS`, `CHECKING`

          Example: `CHECKING`
        </ParamField>

        <ParamField body="document" type="string" required>
          CPF or CNPJ Number.

          Example: `12533009091`
        </ParamField>

        <ParamField body="document_type" type="string" required>
          Document type.

          Allowed values: `cpf`, `cnpj`

          Example: `cpf`
        </ParamField>

        <ParamField body="birthdate" type="string">
          Beneficiary's birthdate.

          Format: `YYYY-MM-DD`

          Example: `1970-01-01`
        </ParamField>

        <ParamField body="phone" type="string">
          Phone number with country code.

          Example: `5541987456321`
        </ParamField>

        <ParamField body="city" type="string">
          City name.

          Example: `Curitiba`
        </ParamField>

        <ParamField body="postal_code" type="string">
          Postal code.

          Example: `80200-100`
        </ParamField>

        <ParamField body="province_code" type="string">
          State/Province code.

          Example: `PR`
        </ParamField>

        <ParamField body="address" type="string">
          Street address.

          Example: `Rua a Número 10`
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Webhook Callback

When you provide a `notification_url`, we will send HTTP POST requests to your endpoint when the data qualification status changes.

<Note>
  **Webhook Signature**: All data qualification webhooks are signed with an sha256 hash provided in the `Authorization` header. The hash is sent as a Bearer token. eg.: `Bearer {hash}`

  To validate the signature you must concatenate the request body and your APIKey used to create the payments and hash this string using the sha256 algorithm. For example: `{JSON_BODY...}APIKEY`
</Note>

### Webhook Payload

<ResponseField name="id" type="string">
  Our ID.

  Example: `1`
</ResponseField>

<ResponseField name="step" type="integer">
  An integer value that indicates the step that the data-qualification process is.

  * `1` - Processing - Intermediary step
  * `2` - Valid data - Final step
  * `3` - Invalid data - Final step
</ResponseField>

<ResponseField name="status_id" type="integer">
  An integer value that indicates the current data-qualification status.

  * `1` - Received - The data qualification is received and will be processed soon
  * `5` - Valid data - Final status
  * `6` - Invalid data - Final status
  * `7` - No Process - The account can not be validated - Final status
</ResponseField>

<ResponseField name="custom_code" type="string">
  Your Custom Code.

  Example: `YOURAPPCODE`
</ResponseField>

<ResponseField name="batch_code" type="string">
  The data qualification batch code.

  Example: `bc101`
</ResponseField>

<ResponseField name="message" type="string">
  The description of the data qualification update.
</ResponseField>

<ResponseField name="name" type="string">
  Beneficiary name.
</ResponseField>

<ResponseField name="document" type="string">
  Beneficiary document.
</ResponseField>

<ResponseField name="bank_code" type="string">
  Bank code.
</ResponseField>

<ResponseField name="bank_branch" type="string">
  Bank branch.
</ResponseField>

<ResponseField name="bank_branch_digit" type="string">
  Bank branch digit.
</ResponseField>

<ResponseField name="account" type="string">
  Account number.
</ResponseField>

<ResponseField name="account_digit" type="string">
  Account digit.
</ResponseField>

<ResponseField name="account_type" type="string">
  Account type: `c` for Checking accounts, `s` for Savings accounts.
</ResponseField>

<ResponseField name="pix_key" type="string">
  PIX key if applicable.
</ResponseField>

## Response

<ResponseField name="200" type="object">
  All data qualification records provided have been successfully processed.
</ResponseField>

<ResponseField name="400" type="object">
  When some of the records provided in the data list have errors during processing.

  <Expandable title="Error Object">
    <ResponseField name="message" type="string">
      Error message.
    </ResponseField>

    <ResponseField name="info" type="object">
      This return object is divided in three properties:

      <Expandable title="Info Object">
        <ResponseField name="errors" type="array">
          Contains the records that have any error during processing.

          <Expandable title="Error Item">
            <ResponseField name="line" type="integer">
              Represents which record in the batch data has errors.
            </ResponseField>

            <ResponseField name="batch_code" type="string">
              The batch\_code provided.
            </ResponseField>

            <ResponseField name="custom_code" type="string">
              The custom\_code provided.
            </ResponseField>

            <ResponseField name="message" type="string">
              Message error description.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="uploadSuccess" type="array">
          Contains the records that have been successfully processed.

          <Expandable title="Success Item">
            <ResponseField name="line" type="integer">
              Represents which record in the batch data was successful.
            </ResponseField>

            <ResponseField name="batch_code" type="string">
              The batch\_code provided.
            </ResponseField>

            <ResponseField name="custom_code" type="string">
              The custom\_code provided.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="uploadChangeService" type="array">
          The records that have the service changed automatically.

          <Expandable title="Changed Service Item">
            <ResponseField name="line" type="integer">
              Represents which record in the batch data had service changed.
            </ResponseField>

            <ResponseField name="batch_code" type="string">
              The batch\_code provided.
            </ResponseField>

            <ResponseField name="custom_code" type="string">
              The custom\_code provided.
            </ResponseField>

            <ResponseField name="message" type="string">
              The new service assigned to record.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer {token}' \
    --header 'Content-Type: application/json' \
    --data '{
      "service_id": 2,
      "data": [
        {
          "custom_code": "DQ001",
          "batch_code": "BATCH001",
          "notification_url": "https://your.endpoint.to.update",
          "beneficiary": {
            "name": "Maria Jose",
            "bank_code": "147",
            "bank_branch": "0000",
            "bank_branch_digit": "1",
            "account": "1030000",
            "account_digit": "1",
            "account_type": "CHECKING",
            "document": "12533009091",
            "document_type": "cpf",
            "birthdate": "1970-01-01",
            "phone": "5541987456321",
            "city": "Curitiba",
            "postal_code": "80200-100",
            "province_code": "PR",
            "address": "Rua a Número 10"
          }
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  async function createDataQualification(data) {
    const response = await fetch(
      'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification',
      {
        method: 'POST',
        headers: {
          'Accept': 'application/json',
          'Authorization': 'Bearer {token}',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          service_id: 2,
          data: [
            {
              custom_code: 'DQ001',
              batch_code: 'BATCH001',
              notification_url: 'https://your.endpoint.to.update',
              beneficiary: {
                name: 'Maria Jose',
                bank_code: '147',
                bank_branch: '0000',
                bank_branch_digit: '1',
                account: '1030000',
                account_digit: '1',
                account_type: 'CHECKING',
                document: '12533009091',
                document_type: 'cpf',
                birthdate: '1970-01-01',
                phone: '5541987456321',
                city: 'Curitiba',
                postal_code: '80200-100',
                province_code: 'PR',
                address: 'Rua a Número 10'
              }
            }
          ]
        })
      }
    );
    
    if (!response.ok) {
      throw new Error(`Failed to create data qualification: ${response.statusText}`);
    }
    
    return await response.json();
  }

  const result = await createDataQualification();
  console.log('Data qualification created:', result);
  ```

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

  def create_data_qualification():
      url = 'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification'
      headers = {
          'Accept': 'application/json',
          'Authorization': 'Bearer {token}',
          'Content-Type': 'application/json'
      }
      
      payload = {
          'service_id': 2,
          'data': [
              {
                  'custom_code': 'DQ001',
                  'batch_code': 'BATCH001',
                  'notification_url': 'https://your.endpoint.to.update',
                  'beneficiary': {
                      'name': 'Maria Jose',
                      'bank_code': '147',
                      'bank_branch': '0000',
                      'bank_branch_digit': '1',
                      'account': '1030000',
                      'account_digit': '1',
                      'account_type': 'CHECKING',
                      'document': '12533009091',
                      'document_type': 'cpf',
                      'birthdate': '1970-01-01',
                      'phone': '5541987456321',
                      'city': 'Curitiba',
                      'postal_code': '80200-100',
                      'province_code': 'PR',
                      'address': 'Rua a Número 10'
                  }
              }
          ]
      }
      
      response = requests.post(url, headers=headers, json=payload)
      response.raise_for_status()
      
      return response.json()

  result = create_data_qualification()
  print('Data qualification created:', result)
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "message": "All records processed successfully"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "message": "Error message.",
    "info": {
      "errors": [
        {
          "line": 1,
          "batch_code": "bc101",
          "custom_code": "cc101",
          "message": "Name format invalid"
        }
      ],
      "uploadSuccess": [
        {
          "line": 2,
          "batch_code": "bc102",
          "custom_code": "cc102"
        }
      ],
      "uploadChangeService": [
        {
          "line": 3,
          "batch_code": "bc103",
          "custom_code": "cc103",
          "message": "Data qualification by system"
        }
      ]
    }
  }
  ```
</ResponseExample>