# Individual Identity

Individual Identities run an end-to-end identity verification on a Brazilian individual. Each entry wraps the proofs (document and/or facial biometrics) the holder must submit; Stark Infra orchestrates the collection, validates each proof and delivers the result through the `individual-identity` webhook subscription.

Identities are created in `created` status and are walked through `processing`, `pending` and finally `success` or `failed` by private workers. Every transition produces an Individual Identity Log.

### The IndividualIdentity object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the individual identity. |
| `name` | STRING | Full name of the holder being verified. |
| `taxId` | STRING | CPF of the holder. Optional at creation; can be patched later. Example: "012.345.678-90". |
| `email` | STRING | E-mail used to deliver the `validatorLink` when `deliveryMethod = automatic`. |
| `phone` | STRING | Holder's phone in international format. Optional. |
| `tags` | LIST OF STRINGS | Tags associated with the individual identity. |
| `proofs` | LIST OF STRINGS | List of proof types required by the identity. Options: `identity`, `biometric`. |
| `deliveryMethod` | STRING | How the `validatorLink` reaches the holder. Options: `automatic`, `manual`. |
| `validatorLink` | STRING | URL the holder opens to submit each proof. Carries the `identityId` encoded in the `info` query parameter. |
| `sourceId` | STRING | Id of the entity that triggered this verification. Filled automatically with the workspace id for external callers. |
| `sourceType` | STRING | Origin of the verification. Options: `onboarding`, `reboarding`, `external`. |
| `workspaceId` | STRING | Id of the workspace that owns this identity. |
| `status` | STRING | Current status of the individual identity. Options: "created", "processing", "pending", "success", "failed". |
| `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 Identities

`POST /v2/individual-identity`

Create one or more Individual Identities. Each entry is returned in `created` status and already carries the `validatorLink` the holder will use to submit each proof.

**Validations:** the workspace must have an Identity Profile; every value in `proofs` must be enabled on that profile.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `name` | REQUIRED | Full name of the holder being verified. |
| `email` | REQUIRED | E-mail used to deliver the `validatorLink` when `deliveryMethod = automatic`. |
| `deliveryMethod` | REQUIRED | How the `validatorLink` reaches the holder. Options: `automatic`, `manual`. |
| `proofs` | REQUIRED | List of proof types to collect. Each item must be one of `identity`, `biometric` and must be enabled on your workspace's Identity Profile. |
| `taxId` | OPTIONAL | CPF of the holder, with or without punctuation. Example: "012.345.678-90". |
| `phone` | OPTIONAL | Holder's phone in international format. Example: "+5511987654321". |
| `tags` | OPTIONAL | List of strings to tag the entity for future queries. |

**Request**

```python
import starkinfra

identities = starkinfra.individualidentity.create([
    starkinfra.IndividualIdentity(
        name="Daenerys Targaryen Stormborn",
        email="daenerys@example.com",
        delivery_method="automatic",
        proofs=["identity", "biometric"],
        tax_id="012.345.678-90",
        phone="+5511987654321",
        tags=["onboarding-123"]
    )
])

for identity in identities:
    print(identity)
```

**Response**

```python
[
    IndividualIdentity(
        id="5740977003561984",
        name="Daenerys Targaryen Stormborn",
        tax_id="012.345.678-90",
        email="daenerys@example.com",
        phone="+5511987654321",
        tags=["onboarding-123"],
        proofs=["identity", "biometric"],
        delivery_method="automatic",
        validator_link="https://starkbank.com/validator-link?info=eyJpZGVudGl0eUlkIjoiNTc0MDk3NzAwMzU2MTk4NCJ9",
        source_id="6480539068923904",
        source_type="external",
        workspace_id="6480539068923904",
        status="created",
        created="2026-06-23T12:00:00.000000+00:00",
        updated="2026-06-23T12:00:00.000000+00:00"
    )
]
```

### List Individual Identities

`GET /v2/individual-identity`

List and filter all individual identities in your workspace. Results are returned paged via cursor.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. Format: ISO 8601 or YYYY-MM-DD. |
| `before` | OPTIONAL | Filter entities created before this date. Format: ISO 8601 or YYYY-MM-DD. |
| `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. |
| `status` | OPTIONAL | Filter identities by the specified status. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `taxIds` | OPTIONAL | List of CPFs to filter the response by. |
| `email` | OPTIONAL | Filter identities by holder e-mail. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra

identities = starkinfra.individualidentity.query(
    status=["pending", "success"],
    tags=["onboarding-123"],
    limit=10
)

for identity in identities:
    print(identity)
```

**Response**

```python
[
    IndividualIdentity(
        id="5740977003561984",
        name="Daenerys Targaryen Stormborn",
        tax_id="012.345.678-90",
        status="pending",
        proofs=["identity", "biometric"],
        delivery_method="automatic",
        created="2026-06-23T12:00:00.000000+00:00",
        updated="2026-06-23T12:00:10.000000+00:00"
    )
]
```

### Get an Individual Identity

`GET /v2/individual-identity/:id`

Get a single individual identity by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the individual identity entity. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra

identity = starkinfra.individualidentity.get("5740977003561984")
print(identity)
```

**Response**

```python
IndividualIdentity(
    id="5740977003561984",
    name="Daenerys Targaryen Stormborn",
    tax_id="012.345.678-90",
    email="daenerys@example.com",
    phone="+5511987654321",
    tags=["onboarding-123"],
    proofs=["identity", "biometric"],
    delivery_method="automatic",
    validator_link="https://starkbank.com/validator-link?info=eyJpZGVudGl0eUlkIjoiNTc0MDk3NzAwMzU2MTk4NCJ9",
    source_id="6480539068923904",
    source_type="external",
    workspace_id="6480539068923904",
    status="success",
    created="2026-06-23T12:00:00.000000+00:00",
    updated="2026-06-23T12:05:30.000000+00:00"
)
```

### Update an Individual Identity

`PATCH /v2/individual-identity/:id`

Update the `taxId` of an individual identity after it has been created. Useful when the CPF is unknown at creation time and is only collected during the proof submission flow.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the individual identity entity. |
| `taxId` | OPTIONAL | CPF to assign to the identity, with or without punctuation. |

**Request**

```python
import starkinfra

identity = starkinfra.individualidentity.update(
    id="5740977003561984",
    tax_id="012.345.678-90"
)

print(identity)
```

**Response**

```python
IndividualIdentity(
    id="5740977003561984",
    name="Daenerys Targaryen Stormborn",
    tax_id="012.345.678-90",
    status="pending",
    proofs=["identity", "biometric"],
    delivery_method="automatic",
    created="2026-06-23T12:00:00.000000+00:00",
    updated="2026-06-23T12:02:00.000000+00:00"
)
```

### Cancel an Individual Identity

`DELETE /v2/individual-identity/:id`

Cancel an individual identity (soft delete). The identity transitions to `failed`, every pending proof is canceled and a `canceled` log is delivered through the webhook. Only identities in `created` or `pending` status can be canceled.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the individual identity entity. |

**Request**

```python
import starkinfra

identity = starkinfra.individualidentity.cancel("5740977003561984")
print(identity)
```

**Response**

```python
IndividualIdentity(
    id="5740977003561984",
    name="Daenerys Targaryen Stormborn",
    status="failed",
    proofs=["identity", "biometric"],
    delivery_method="automatic",
    created="2026-06-23T12:00:00.000000+00:00",
    updated="2026-06-23T12:03:00.000000+00:00"
)
```

### List Individual Identity Logs

`GET /v2/individual-identity/log`

Get a paged list of all individual identity logs. A log tracks a change in the individual identity entity according to its lifecycle.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `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. |
| `identityIds` | OPTIONAL | List of individual identity ids linked to the desired logs. Max = 100. |
| `types` | OPTIONAL | Filter logs by log type. Options: "created", "processing", "pending", "updated", "success", "failed", "canceled", "expired". |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra

logs = starkinfra.individualidentity.log.query(
    types=["success", "failed"],
    identity_ids=["5740977003561984"],
    limit=10
)

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

**Response**

```python
[
    IndividualIdentityLog(
        id="6661702144623308",
        type="success",
        identity=IndividualIdentity(id="5740977003561984", status="success"),
        errors=[],
        created="2026-06-23T12:05:30.000000+00:00"
    )
]
```

### Get an Individual Identity Log

`GET /v2/individual-identity/log/:id`

Get a single individual identity log by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the individual identity log entity. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra

log = starkinfra.individualidentity.log.get("6661702144623308")
print(log)
```

**Response**

```python
IndividualIdentityLog(
    id="6661702144623308",
    type="success",
    identity=IndividualIdentity(id="5740977003561984", status="success"),
    errors=[],
    created="2026-06-23T12:05:30.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-identity-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/individual-identity-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/individual-identity-php.md)
- [Java](https://docs.starkinfra.com/api/v2/individual-identity-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/individual-identity-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/individual-identity-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/individual-identity-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/individual-identity-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/individual-identity-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/individual-identity-curl.md)