# Individual Account Request

An Individual Account Request asks Stark Infra to open an account for a natural person. You submit the individual's identifying data and income, upload the required document images as Individual Account Attachments, 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 against the identity bureaus and writes the final `approved` or `denied` status together with any review `flags`. Every transition produces an Individual Account Request Log.

### The IndividualAccountRequest object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id returned when the individual account request is created. Example: "5656565656565656". |
| `taxId` | STRING | CPF of the individual, always returned formatted. Example: "012.345.678-90". |
| `name` | STRING | Full name of the individual. Example: "Tony Stark". |
| `address` | OBJECT | Structured residential address of the individual. Returned as the nested object you sent, with the keys `street`, `number`, `neighborhood`, `city`, `state`, `zipCode` and, when informed, `complement`. Returned as an empty string when no address is stored. |
| `income` | INTEGER | Individual's income in cents. Example: 1000000 (R$10,000.00). |
| `birthDate` | STRING | Birth date of the individual. Returned as an empty string when it was not informed. Example: "1965-09-07". |
| `status` | STRING | Current status of the individual account request. Options: "created", "processing", "denied", "approved". |
| `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` plus the values that describe it. Example: ``` [{"code": "individualSanctions", "parameter": "012.345.678-90"}] ``` |
| `tags` | LIST OF STRINGS | Tags associated with the individual account request, always returned lowercased. Example: ["employees", "monthly"]. |
| `accountType` | STRING | Type of account requested. Always "individual" 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 Individual Account Requests

`POST /v2/individual-account-request`

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

**NOTE:** Creating a request does not start the validation. Attach the required documents first, then patch the request's status to `processing`.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `name` | REQUIRED | Full name of the individual. Must be a string of at least 5 characters. Example: "Tony Stark". |
| `taxId` | REQUIRED | CPF of the individual, either as 11 bare digits or fully punctuated. Example: "012.345.678-90". |
| `income` | REQUIRED | Individual's income in cents. Must be an integer greater than or equal to zero. Example: 1000000 (R$10,000.00). |
| `address` | REQUIRED | Structured residential address of the individual. 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": "Rua do Estilo Barroco", "number": "648", "neighborhood": "Santo Amaro", "city": "Sao Paulo", "state": "SP", "zipCode": "05724005"} ``` |
| `birthDate` | OPTIONAL | Birth date of the individual. Expected format: YYYY-MM-DD. Example: "1965-09-07". |
| `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.individualaccountrequest.create([
    starkinfra.IndividualAccountRequest(
        name="Tony Stark",
        tax_id="012.345.678-90",
        address=starkinfra.individualaccountrequest.Address(
            street="Rua do Estilo Barroco",
            number="648",
            neighborhood="Santo Amaro",
            city="Sao Paulo",
            state="SP",
            zip_code="05724005"
        ),
        income=1000000,
        birth_date="1965-09-07",
        tags=["employees", "monthly"]
    )
])

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

**Response**

```python
[
    IndividualAccountRequest(
        id="5656565656565656",
        name="Tony Stark",
        tax_id="012.345.678-90",
        address=Address(
            street="Rua do Estilo Barroco",
            number="648",
            neighborhood="Santo Amaro",
            city="Sao Paulo",
            state="SP",
            zip_code="05724005"
        ),
        income=1000000,
        birth_date="1965-09-07",
        tags=["employees", "monthly"],
        account_type="individual",
        flags=[],
        status="created",
        created="2026-06-23T12:00:00.000000+00:00",
        updated="2026-06-23T12:00:00.000000+00:00"
    )
]
```

### List Individual Account Requests

`GET /v2/individual-account-request`

Use this route to list and filter the individual 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". |
| `tags` | OPTIONAL | Filter entities that contain any of the specified tags. Max = 30. |
| `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.individualaccountrequest.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
[
    IndividualAccountRequest(
        id="5656565656565656",
        name="Tony Stark",
        tax_id="012.345.678-90",
        address=Address(
            street="Rua do Estilo Barroco",
            number="648",
            neighborhood="Santo Amaro",
            city="Sao Paulo",
            state="SP",
            zip_code="05724005"
        ),
        income=1000000,
        birth_date="1965-09-07",
        tags=["employees", "monthly"],
        account_type="individual",
        flags=[],
        status="created",
        created="2026-06-23T12:00:00.000000+00:00",
        updated="2026-06-23T12:00:00.000000+00:00"
    )
]
```

### Get an Individual Account Request

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

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

**Parameters**

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

**Request**

```python
import starkinfra

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

print(request)
```

**Response**

```python
IndividualAccountRequest(
    id="5656565656565656",
    name="Tony Stark",
    tax_id="012.345.678-90",
    address=Address(
        street="Rua do Estilo Barroco",
        number="648",
        neighborhood="Santo Amaro",
        city="Sao Paulo",
        state="SP",
        zip_code="05724005"
    ),
    income=1000000,
    birth_date="1965-09-07",
    tags=["employees", "monthly"],
    account_type="individual",
    flags=[],
    status="approved",
    created="2026-06-23T12:00:00.000000+00:00",
    updated="2026-06-23T12:10:45.000000+00:00"
)
```

### Update an Individual Account Request

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

Use this route to correct the data of an individual 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 a complete document set 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 individual account request entity. Example: "5656565656565656". |
| `status` | OPTIONAL | Status to send the request to validation. Options: "processing". |
| `name` | OPTIONAL | New full name of the individual. Must be a string of at least 5 characters. Example: "Tony Stark". |
| `taxId` | OPTIONAL | New CPF of the individual, either as 11 bare digits or fully punctuated. Example: "012.345.678-90". |
| `income` | OPTIONAL | New income in cents. Must be an integer greater than or equal to zero. Example: 1500000 (R$15,000.00). |
| `address` | OPTIONAL | New structured residential address. 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"} ``` |
| `birthDate` | OPTIONAL | New birth date of the individual. Expected format: YYYY-MM-DD. Example: "1965-09-07". |
| `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.individualaccountrequest.update(
    "5656565656565656",
    status="processing"
)

print(request)
```

**Response**

```python
IndividualAccountRequest(
    id="5656565656565656",
    name="Tony Stark",
    tax_id="012.345.678-90",
    address=Address(
        street="Rua do Estilo Barroco",
        number="648",
        neighborhood="Santo Amaro",
        city="Sao Paulo",
        state="SP",
        zip_code="05724005"
    ),
    income=1000000,
    birth_date="1965-09-07",
    tags=["employees", "monthly"],
    account_type="individual",
    flags=[],
    status="processing",
    created="2026-06-23T12:00:00.000000+00:00",
    updated="2026-06-23T12:05:30.000000+00:00"
)
```

### List Individual Account Request Logs

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

Use this route to get a paged list of individual account request logs. A log tracks a change in the individual 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". |
| `accountRequestIds` | OPTIONAL | List of individual 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.individualaccountrequest.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=IndividualAccountRequest(
        id="5656565656565656",
        name="Tony Stark",
        tax_id="012.345.678-90",
        address=Address(
            street="Rua do Estilo Barroco",
            number="648",
            neighborhood="Santo Amaro",
            city="Sao Paulo",
            state="SP",
            zip_code="05724005"
        ),
        income=1000000,
        birth_date="1965-09-07",
        tags=["employees", "monthly"],
        account_type="individual",
        flags=[{"code": "individualSanctions", "parameter": "OFAC SDN"}],
        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 an Individual Account Request Log

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the individual 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.individualaccountrequest.log.get("4545454545454545")

print(log)
```

**Response**

```python
Log(
    id="4545454545454545",
    type="denied",
    errors=[],
    request=IndividualAccountRequest(
        id="5656565656565656",
        name="Tony Stark",
        tax_id="012.345.678-90",
        address=Address(
            street="Rua do Estilo Barroco",
            number="648",
            neighborhood="Santo Amaro",
            city="Sao Paulo",
            state="SP",
            zip_code="05724005"
        ),
        income=1000000,
        birth_date="1965-09-07",
        tags=["employees", "monthly"],
        account_type="individual",
        flags=[{"code": "individualSanctions", "parameter": "OFAC SDN"}],
        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/individual-account-request-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/individual-account-request-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/individual-account-request-php.md)
- [Java](https://docs.starkinfra.com/api/v2/individual-account-request-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/individual-account-request-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/individual-account-request-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/individual-account-request-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/individual-account-request-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/individual-account-request-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/individual-account-request-curl.md)