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

# Account Opening Request

> API for creating onboarding requests for corporate account (legal entities). To successfully create a corporate account, you must provide at least one administrator and one legal representative.

## Allowed Roles

| Role                  | Required |
| --------------------- | -------- |
| administrator         | ✓        |
| legal\_representative | ✓        |
| financial             | ✗        |
| commercial            | ✗        |

## Request Body

<ParamField body="legal_name" type="string" required>
  Official registered name of the company as it appears in legal documents.

  * Min: 1 character
  * Max: 100 characters
  * Example: `Company X LTDA`
</ParamField>

<ParamField body="trade_name" type="string" required>
  Common or commercial name used by the company in business operations.

  * Min: 1 character
  * Max: 100 characters
  * Example: `Company X`
</ParamField>

<ParamField body="tax_id" type="string" required>
  Company's tax identification number (CNPJ for Brazilian companies), without formatting.

  * If country = BR: max 14 characters (valid CNPJ)
  * If country ≠ BR: max 50 characters
  * Example: `12345678000199`
</ParamField>

<ParamField body="contacts" type="array[object]" required>
  List of individuals associated with the company, such as administrators, legal representatives, or other relevant roles.

  <Expandable title="Contact Object">
    <ParamField body="name" type="string" required>
      Full name of the contact person.

      * Min: 1 character
      * Max: 120 characters
      * Example: `João Silva`
    </ParamField>

    <ParamField body="email" type="string" required>
      Contact's professional email address.

      * Max: 100 characters
      * Example: `joao.silva@companyx.com`
    </ParamField>

    <ParamField body="phone" type="string" required>
      Contact's phone number, including country and area code.

      * Max: 15 characters
      * Example: `5511999999999`
    </ParamField>

    <ParamField body="role" type="string" required>
      Role of the contact person within the company. Must be one of the allowed roles.

      * Allowed values: `administrator`, `legal_representative`, `financial`, `commercial`
      * Example: `administrator`
    </ParamField>

    <ParamField body="tax_id" type="string" required>
      Personal tax identification number of the contact (CPF for Brazil), without formatting.

      * If country = BR: max 11 characters (valid CPF)
      * If country ≠ BR: max 30 characters
      * Example: `12345678909`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="address" type="object" required>
  Company's main business address.

  <Expandable title="Address Object">
    <ParamField body="city" type="string" required>
      City where the company is located.

      * Max: 40 characters
      * Example: `São Paulo`
    </ParamField>

    <ParamField body="state" type="string" required>
      State or province where the company is located (ISO code preferred).

      * Max: 4 characters
      * Example: `SP`
    </ParamField>

    <ParamField body="country" type="string" required>
      Country code where the company is registered (ISO 3166-1 alpha-2 format).

      * Max: 4 characters
      * Example: `BR`
    </ParamField>

    <ParamField body="zip_code" type="string" required>
      Postal code of the company address, without formatting.

      * Max: 12 characters
      * Example: `01001000`
    </ParamField>

    <ParamField body="street" type="string" required>
      Street name of the company address.

      * Max: 80 characters
      * Example: `Av. Paulista`
    </ParamField>

    <ParamField body="number" type="string">
      Street number of the company address.

      * Max: 10 characters
      * Example: `1000`
    </ParamField>

    <ParamField body="complement" type="string">
      Additional address details, such as suite, floor, or unit.

      * Max: 80 characters
      * Example: `Conjunto 12`
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier of the corporate subaccount opening request.

  * Format: UUID
  * Example: `339074a8-1834-49c5-af94-4a044248d88d`
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the onboarding request.

  * Default: `pending`
</ResponseField>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": "339074a8-1834-49c5-af94-4a044248d88d",
    "status": "pending"
  }
  ```

  ```json 422 Unprocessable Entity theme={null}
  {
    "error": "Validation error"
  }
  ```
</ResponseExample>

## Related Resources

<CardGroup cols={2}>
  <Card title="Setup Webhook" icon="webhook" href="/api-reference/account/webhook/webhook-setup">
    Configure webhook notifications for onboarding events
  </Card>

  <Card title="Update Webhook" icon="pen-to-square" href="/api-reference/account/webhook/webhook-update">
    Update existing webhook configuration
  </Card>
</CardGroup>