# Individual Identity Proof

Each Individual Identity Proof represents one piece of evidence required by the parent Individual Identity. One proof is generated per `proofType` requested at creation; the holder submits the content via `PATCH /v2/individual-identity-proof/:id`.

Proofs go through their own lifecycle (`pending` → `processing` → `success` / `failed` / `canceled` / `expired`). The parent identity transitions to `success` only when every proof reaches `success`.

### The IndividualIdentityProof object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the individual identity proof. |
| `proofType` | STRING | Type of evidence required. Options: `identity`, `biometric`. |
| `metadata` | DICTIONARY | Raw payload returned by the provider after the proof is validated. Empty until the proof reaches `processing`. |
| `status` | STRING | Current status of the proof. Options: "pending", "processing", "success", "failed", "canceled", "expired". |
| `individualIdentityId` | STRING | Id of the parent individual identity. |
| `created` | STRING | Creation datetime. Example: "2026-06-23T12:00:10.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2026-06-23T12:03:00.000000+00:00". |

### List Individual Identity Proofs

`GET /v2/individual-identity-proof`

List the proofs tied to an Individual Identity. The `identityId` query parameter is required.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `identityId` | REQUIRED | Id of the parent individual identity whose proofs you want to list. |
| `status` | OPTIONAL | Filter proofs by status. |
| `proofType` | OPTIONAL | Filter proofs by `proofType`. Options: `identity`, `biometric`. |
| `ids` | OPTIONAL | List of strings to get specific proofs by ids. |
| `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. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra

proofs = starkinfra.request.get(
    path="/individual-identity-proof",
    query={
        "identityId": "5740977003561984",
        "status": ["pending", "processing"],
        "limit": 10
    }
).json()

print(proofs)
```

**Response**

```python
{
    'cursor': None,
    'proofs': [
        {
            'id': '4512334302912512',
            'proofType': 'biometric',
            'metadata': {},
            'status': 'pending',
            'individualIdentityId': '5740977003561984',
            'created': '2026-06-23T12:00:10.000000+00:00',
            'updated': '2026-06-23T12:00:10.000000+00:00'
        }
    ]
}
```

### Get an Individual Identity Proof

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

Get a single individual identity proof by its id.

**Parameters**

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

**Request**

```python
import starkinfra

proof = starkinfra.request.get(
    path="/individual-identity-proof/4512334302912512"
).json()

print(proof)
```

**Response**

```python
{
    'proof': {
        'id': '4512334302912512',
        'proofType': 'identity',
        'metadata': {'documentId': 'doc-abc-123', 'documentType': 'RG'},
        'status': 'success',
        'individualIdentityId': '5740977003561984',
        'created': '2026-06-23T12:00:10.000000+00:00',
        'updated': '2026-06-23T12:03:00.000000+00:00'
    }
}
```

### Submit an Individual Identity Proof

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

Submit the content of a proof. This is the step in which the holder's document or biometric is uploaded for validation.

**biometric** — `content` is a base64 image string with the facial selfie.

**identity** — `content` is a JSON-serialised string carrying the provider's `documentId` and/or the document `file` (base64 image).

After a successful PATCH the proof transitions from `pending` to `processing` and the provider validates it asynchronously.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the individual identity proof being submitted. |
| `content` | REQUIRED | Content of the proof, encoded according to the `proofType`. |

**Request**

```python
import starkinfra

proof = starkinfra.request.patch(
    path="/individual-identity-proof/4512334302912512",
    body={
        "content": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
    }
).json()

print(proof)
```

**Response**

```python
{
    'proof': {
        'id': '4512334302912512',
        'proofType': 'biometric',
        'metadata': {},
        'status': 'processing',
        'individualIdentityId': '5740977003561984',
        'created': '2026-06-23T12:00:10.000000+00:00',
        'updated': '2026-06-23T12:02:00.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-proof-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/individual-identity-proof-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/individual-identity-proof-php.md)
- [Java](https://docs.starkinfra.com/api/v2/individual-identity-proof-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/individual-identity-proof-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/individual-identity-proof-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/individual-identity-proof-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/individual-identity-proof-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/individual-identity-proof-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/individual-identity-proof-curl.md)