# Business Account Request

A Business Account Request asks Stark Infra to open an account for a company. You submit the company's legal name, its CNPJ, its structured address, its annual revenue and the list of its owners, upload the corporate documents, and then send the request to validation by patching its status to `processing`.

Requests are created in `created` status. Once sent to validation, a private worker runs the KYC pipeline over the company and each of its owners and writes the final `approved` or `denied` status together with any review `flags`. A request whose bureau lookups keep erroring ends in `failed` instead. Every transition produces a Business Account Request Log.

### The BusinessAccountRequest object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id returned when the business account request is created. Example: "5656565656565656". |
| `taxId` | STRING | CNPJ of the company, always returned formatted. Example: "20.018.183/0001-80". |
| `name` | STRING | Legal name of the company. Example: "Stark Bank S.A.". |
| `address` | OBJECT | Structured address of the company. Returned as the nested object you sent, with the keys `street`, `number`, `neighborhood`, `city`, `state`, `zipCode` and, when informed, `complement`. Returned as null when no address is stored. |
| `owners` | LIST OF OBJECTS | Owners of the company, from 1 to 10 entries. Each entry carries the `taxId`, `name` and `role` you sent, plus the return-only `identityId`, `validatorLink` and `status` of that owner's identity verification. Example: ``` [{"taxId": "012.345.678-90", "name": "Jamie Lannister", "role": "partner", "identityId": "5709594221805568", "validatorLink": "https://validator.starkinfra.com/5709594221805568", "status": "created"}] ``` |
| `revenue` | INTEGER | Company's annual revenue in cents. Example: 100000000 (R$1,000,000.00). |
| `status` | STRING | Current status of the business account request. Options: "created", "processing", "denied", "approved", "failed". |
| `flags` | LIST OF OBJECTS | Review flags raised by the KYC pipeline. Empty until the request is validated, and empty on an approved request with no restriction. Each flag carries a `code` and the `message` that describes it. Example: ``` [{"code": "failedIdentityProof", "message": "O representante: 012.345.678-90 falhou na verificacao de identidade."}] ``` |
| `tags` | LIST OF STRINGS | Tags associated with the business account request, always returned lowercased. Example: ["employees", "monthly"]. |
| `accountType` | STRING | Type of account requested. Always "business" for this resource. Options: "individual", "business". |
| `created` | STRING | Creation datetime. Example: "2026-06-23T12:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2026-06-23T12:05:30.000000+00:00". |

### Create Business Account Requests

`POST /v2/business-account-request`

Use this route to create up to 100 new business account requests at a time. Each entry is returned in `created` status.

**NOTE:** Creating a request does not start the validation. Attach a corporate document first, deliver each owner's `validatorLink`, then patch the request's status to `processing`.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `name` | REQUIRED | Legal name of the company. Must be a string of at least 5 characters. Example: "Stark Bank S.A.". |
| `taxId` | REQUIRED | CNPJ of the company, either as 14 bare digits or fully punctuated. Example: "20.018.183/0001-80". |
| `revenue` | REQUIRED | Company's annual revenue in cents. Must be an integer greater than or equal to zero. Example: 100000000 (R$1,000,000.00). |
| `address` | REQUIRED | Structured address of the company. The keys `street`, `number`, `neighborhood`, `city`, `state` and `zipCode` are all required and must be non-empty strings; `complement` is the only other key accepted, and any additional key is rejected. Example: ``` {"street": "Av. Faria Lima", "number": "2000", "neighborhood": "Itaim Bibi", "city": "Sao Paulo", "state": "SP", "zipCode": "04538-132"} ``` |
| `owners` | REQUIRED | List of 1 to 10 owners of the company. Each entry requires `taxId` (CPF), `name` and `role`. Options for `role`: "partner", "representative". Example: ``` [{"taxId": "012.345.678-90", "name": "Jamie Lannister", "role": "partner"}] ``` |
| `tags` | OPTIONAL | List of up to 100 strings to tag the entity for future queries. Each tag is limited to 100 characters and is stored lowercased. Example: ["employees", "monthly"]. |

**Request**

```python
import starkinfra

requests = starkinfra.businessaccountrequest.create([
    starkinfra.BusinessAccountRequest(
        name="Stark Bank S.A.",
        tax_id="20.018.183/0001-80",
        revenue=100000000,
        address=starkinfra.businessaccountrequest.Address(
            street="Av. Faria Lima",
            number="2000",
            neighborhood="Itaim Bibi",
            city="Sao Paulo",
            state="SP",
            zip_code="04538-132"
        ),
        owners=[
            starkinfra.businessaccountrequest.Owner(
                tax_id="012.345.678-90",
                name="Jamie Lannister",
                role="partner"
            )
        ],
        tags=["employees", "monthly"]
    )
])

for request in requests:
    print(request)
```

**Response**

```python
[
    BusinessAccountRequest(
        id="5656565656565656",
        name="Stark Bank S.A.",
        tax_id="20.018.183/0001-80",
        address=Address(
            street="Av. Faria Lima",
            number="2000",
            neighborhood="Itaim Bibi",
            city="Sao Paulo",
            state="SP",
            zip_code="04538-132"
        ),
        owners=[
            Owner(
                tax_id="012.345.678-90",
                name="Jamie Lannister",
                role="partner",
                identity_id="5709594221805568",
                validator_link="https://validator.starkinfra.com/5709594221805568",
                status="created"
            )
        ],
        revenue=100000000,
        tags=["employees", "monthly"],
        account_type="business",
        flags=[],
        status="created",
        created="2026-06-23T12:00:00.000000+00:00",
        updated="2026-06-23T12:00:00.000000+00:00"
    )
]
```

### List Business Account Requests

`GET /v2/business-account-request`

Use this route to list and filter the business account requests in your workspace. Results are returned paged via cursor, from the most recently created to the oldest.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. Format: ISO 8601 or YYYY-MM-DD. Example: "2026-06-01". |
| `before` | OPTIONAL | Filter entities created before this date. Format: ISO 8601 or YYYY-MM-DD. Example: "2026-06-30". |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. Default = 100. |
| `status` | OPTIONAL | Filter requests by the specified statuses. Options: "created", "processing", "denied", "approved", "failed". |
| `tags` | OPTIONAL | Filter entities that contain any of the specified tags. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. Max = 100. When informed, every other filter is applied in memory over these ids and no cursor is returned. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra
from datetime import date

requests = starkinfra.businessaccountrequest.query(
    limit=10,
    after=date(2026, 6, 1),
    before=date(2026, 6, 30),
    status=["created", "processing"],
    tags=["employees", "monthly"]
)

for request in requests:
    print(request)
```

**Response**

```python
[
    BusinessAccountRequest(
        id="5656565656565656",
        name="Stark Bank S.A.",
        tax_id="20.018.183/0001-80",
        address=Address(
            street="Av. Faria Lima",
            number="2000",
            neighborhood="Itaim Bibi",
            city="Sao Paulo",
            state="SP",
            zip_code="04538-132"
        ),
        owners=[
            Owner(
                tax_id="012.345.678-90",
                name="Jamie Lannister",
                role="partner",
                identity_id="5709594221805568",
                validator_link="https://validator.starkinfra.com/5709594221805568",
                status="created"
            )
        ],
        revenue=100000000,
        tags=["employees", "monthly"],
        account_type="business",
        flags=[],
        status="created",
        created="2026-06-23T12:00:00.000000+00:00",
        updated="2026-06-23T12:00:00.000000+00:00"
    )
]
```

### Get a Business Account Request

`GET /v2/business-account-request/:id`

Use this route to get a single business account request by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the business account request entity. Example: "5656565656565656". |

**Request**

```python
import starkinfra

request = starkinfra.businessaccountrequest.get("5656565656565656")

print(request)
```

**Response**

```python
BusinessAccountRequest(
    id="5656565656565656",
    name="Stark Bank S.A.",
    tax_id="20.018.183/0001-80",
    address=Address(
        street="Av. Faria Lima",
        number="2000",
        neighborhood="Itaim Bibi",
        city="Sao Paulo",
        state="SP",
        zip_code="04538-132"
    ),
    owners=[
        Owner(
            tax_id="012.345.678-90",
            name="Jamie Lannister",
            role="partner",
            identity_id="5709594221805568",
            validator_link="https://validator.starkinfra.com/5709594221805568",
            status="approved"
        )
    ],
    revenue=100000000,
    tags=["employees", "monthly"],
    account_type="business",
    flags=[],
    status="approved",
    created="2026-06-23T12:00:00.000000+00:00",
    updated="2026-06-23T12:10:45.000000+00:00"
)
```

### Update a Business Account Request

`PATCH /v2/business-account-request/:id`

Use this route to correct the data of a business account request, or to send it to validation by patching its status to `processing`. Every parameter is optional, and the ones you omit are left untouched.

**NOTE:** `processing` is the only status you may send, it is only accepted for a request currently in `created` status, and it is only accepted once an `article-of-incorporation` or a `general-meeting-minute` attachment has been attached to the request. Sending it also moves every `created` attachment of the request to `processing`.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the business account request entity. Example: "5656565656565656". |
| `status` | OPTIONAL | Status to send the request to validation. Options: "processing". |
| `name` | OPTIONAL | New legal name of the company. Must be a string of at least 5 characters. Example: "Stark Bank S.A.". |
| `taxId` | OPTIONAL | New CNPJ of the company, either as 14 bare digits or fully punctuated. Example: "20.018.183/0001-80". |
| `revenue` | OPTIONAL | New annual revenue in cents. Must be an integer greater than or equal to zero. Example: 150000000 (R$1,500,000.00). |
| `address` | OPTIONAL | New structured address of the company. Replaces the stored address as a whole, it is not deep-merged, so send every required key again. Example: ``` {"street": "Avenida Paulista", "number": "1000", "neighborhood": "Bela Vista", "city": "Sao Paulo", "state": "SP", "zipCode": "01310100"} ``` |
| `tags` | OPTIONAL | New list of up to 100 strings to tag the entity. Replaces the stored list as a whole. Example: ["employees", "monthly"]. |

**Request**

```python
import starkinfra

request = starkinfra.request.patch(
    path="/business-account-request/5656565656565656",
    body={
        "status": "processing"
    }
).json()

print(request)
```

**Response**

```python
{
    'request': {
        'accountType': 'business',
        'address': {
            'city': 'Sao Paulo',
            'neighborhood': 'Itaim Bibi',
            'number': '2000',
            'state': 'SP',
            'street': 'Av. Faria Lima',
            'zipCode': '04538-132'
        },
        'created': '2026-06-23T12:00:00.000000+00:00',
        'flags': [],
        'id': '5656565656565656',
        'name': 'Stark Bank S.A.',
        'owners': [
            {
                'identityId': '5709594221805568',
                'name': 'Jamie Lannister',
                'role': 'partner',
                'status': 'created',
                'taxId': '012.345.678-90',
                'validatorLink': 'https://validator.starkinfra.com/5709594221805568'
            }
        ],
        'revenue': 100000000,
        'status': 'processing',
        'tags': ['employees', 'monthly'],
        'taxId': '20.018.183/0001-80',
        'updated': '2026-06-23T12:05:30.000000+00:00'
    }
}
```

### List Business Account Request Logs

`GET /v2/business-account-request/log`

Use this route to get a paged list of business account request logs. A log tracks a change in the business account request entity according to its life cycle.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. Format: ISO 8601 or YYYY-MM-DD. Example: "2026-06-01". |
| `before` | OPTIONAL | Filter entities created before this date. Format: ISO 8601 or YYYY-MM-DD. Example: "2026-06-30". |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. Default = 100. |
| `types` | OPTIONAL | Filter logs by log type. Options: "created", "processing", "updated", "denied", "approved", "failed". |
| `accountRequestIds` | OPTIONAL | List of business account request ids linked to the desired logs. Max = 100. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra
from datetime import date

logs = starkinfra.businessaccountrequest.log.query(
    limit=50,
    after=date(2026, 6, 1),
    before=date(2026, 6, 30),
    types=["approved", "denied"],
    account_request_ids=["5656565656565656"]
)

for log in logs:
    print(log)
```

**Response**

```python
Log(
    id="4545454545454545",
    type="denied",
    errors=[],
    request=BusinessAccountRequest(
        id="5656565656565656",
        name="Stark Bank S.A.",
        tax_id="20.018.183/0001-80",
        address=Address(
            street="Av. Faria Lima",
            number="2000",
            neighborhood="Itaim Bibi",
            city="Sao Paulo",
            state="SP",
            zip_code="04538-132"
        ),
        owners=[
            Owner(
                tax_id="012.345.678-90",
                name="Jamie Lannister",
                role="partner",
                identity_id="5709594221805568",
                validator_link="https://validator.starkinfra.com/5709594221805568",
                status="denied"
            )
        ],
        revenue=100000000,
        tags=["employees", "monthly"],
        account_type="business",
        flags=[{"code": "failedIdentityProof", "message": "O representante: 012.345.678-90 falhou na verificacao de identidade."}],
        status="denied",
        created="2026-06-23T12:00:00.000000+00:00",
        updated="2026-06-23T12:10:45.000000+00:00"
    ),
    created="2026-06-23T12:10:45.000000+00:00"
)
```

### Get a Business Account Request Log

`GET /v2/business-account-request/log/:id`

Use this route to get a single business account request log by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the business account request log entity. Example: "5656565656565656". |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra

log = starkinfra.businessaccountrequest.log.get("4545454545454545")

print(log)
```

**Response**

```python
Log(
    id="4545454545454545",
    type="denied",
    errors=[],
    request=BusinessAccountRequest(
        id="5656565656565656",
        name="Stark Bank S.A.",
        tax_id="20.018.183/0001-80",
        address=Address(
            street="Av. Faria Lima",
            number="2000",
            neighborhood="Itaim Bibi",
            city="Sao Paulo",
            state="SP",
            zip_code="04538-132"
        ),
        owners=[
            Owner(
                tax_id="012.345.678-90",
                name="Jamie Lannister",
                role="partner",
                identity_id="5709594221805568",
                validator_link="https://validator.starkinfra.com/5709594221805568",
                status="denied"
            )
        ],
        revenue=100000000,
        tags=["employees", "monthly"],
        account_type="business",
        flags=[{"code": "failedIdentityProof", "message": "O representante: 012.345.678-90 falhou na verificacao de identidade."}],
        status="denied",
        created="2026-06-23T12:00:00.000000+00:00",
        updated="2026-06-23T12:10:45.000000+00:00"
    ),
    created="2026-06-23T12:10:45.000000+00:00"
)
```

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

- [Python](https://docs.starkinfra.com/api/v2/business-account-request-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/business-account-request-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/business-account-request-php.md)
- [Java](https://docs.starkinfra.com/api/v2/business-account-request-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/business-account-request-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/business-account-request-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/business-account-request-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/business-account-request-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/business-account-request-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/business-account-request-curl.md)