# Business Identity

BusinessIdentities validate the identity of a legal entity (CNPJ) and feed its corporate documents into the Contract AI model.

After creating an identity, upload one or more Business Attachments referencing the returned `id` and PATCH the identity to `processing`. The structured signing rules extracted by the AI Model are delivered through the `business-identity` webhook when the identity reaches `success`.

### The BusinessIdentity object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the business identity. |
| `taxId` | STRING | CNPJ of the legal entity. Example: "20.018.183/0001-80". |
| `name` | STRING | Legal name of the company, fetched from the official bureau on creation. |
| `taxIdStatus` | STRING | Bureau status of the CNPJ, normalized from the Receita Federal value. Mapping: "active" = "ATIVA", "blocked" = "SUSPENSA", "pending" = "INAPTA", "canceled" = "BAIXADA", "voided" = "NULA". |
| `insightTaxId` | STRING | CNPJ extracted from the corporate documents by the AI Model. Empty until the analysis completes. |
| `insightDocumentType` | STRING | Document type detected by the AI Model. Empty until the analysis completes. |
| `representatives` | STRING | JSON string with the company's representatives (sócios) fetched from the bureau. Decode it to access each entry's `name`, `qualification` and `taxId`. |
| `attachments` | LIST OF STRINGS | List of `attachment/<id>` strings referencing the Business Attachments uploaded for this identity. |
| `numPages` | INTEGER | Number of pages of the attached documents, extracted by the AI Model. 0 until the analysis completes. |
| `rules` | STRING | JSON string with the signing rules extracted by the AI Model. Decode it to access each entry's `reference`, `content`, `signaturesRequired` and `eligibles[]` with `name`, `taxId`, `role`, `isSignatureRequired` and `isRepresentative`. Empty string (not an empty list) until the analysis completes. |
| `tags` | LIST OF STRINGS | Tags associated with the business identity. |
| `status` | STRING | Current status of the business identity. Options: "created", "pending", "processing", "canceled", "success", "failed". |
| `created` | STRING | Creation datetime. Example: "2026-06-12T12:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2026-06-12T12:00:00.000000+00:00". |

### Create Business Identities

`POST /v2/business-identity`

Create one or more BusinessIdentities to start the Contract AI flow.

Each entry is created in `pending` status. Save the returned `id` — you'll use it as `identityId` when uploading the Business Attachments and as the path parameter on subsequent calls.

**Validations:** the CNPJ must be valid, must be active in the official bureau and must return non-empty `representatives` (sócios).

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `taxId` | REQUIRED | CNPJ of the legal entity, with or without punctuation. Example: "20.018.183/0001-80". |
| `tags` | OPTIONAL | List of strings to tag the entity for future queries. |

**Request**

```python
import starkinfra

identities = starkinfra.businessidentity.create([
    starkinfra.BusinessIdentity(
        tax_id="20.018.183/0001-80",
        tags=["onboarding-123"]
    )
])

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

**Response**

```python
[
    BusinessIdentity(
        id="5740539971076096",
        tax_id="20.018.183/0001-80",
        name="STARK BANK S.A.",
        tax_id_status="active",
        insight_tax_id="",
        insight_document_type="",
        representatives=[{"name": "Daenerys Targaryen Stormborn", "qualification": "Diretor", "taxId": "012.345.678-90"}],
        attachments=[],
        rules=[],
        tags=["onboarding-123"],
        status="pending",
        created="2026-06-12T12:00:00+00:00",
        updated="2026-06-12T12:00:00+00:00"
    )
]
```

### List Business Identities

`GET /v2/business-identity`

List and filter all business 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. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `taxIds` | OPTIONAL | List of CNPJs to filter the response by. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra

identities = starkinfra.businessidentity.query(
    after="2026-06-01",
    before="2026-06-30",
    status="success",
    tags=["onboarding-123"],
    limit=10
)

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

**Response**

```python
[
    BusinessIdentity(
        id="5740539971076096",
        tax_id="20.018.183/0001-80",
        name="STARK BANK S.A.",
        tax_id_status="active",
        insight_tax_id="20.018.183/0001-80",
        insight_document_type="articles-of-incorporation",
        representatives=[{"name": "Daenerys Targaryen Stormborn", "qualification": "Diretor", "taxId": "012.345.678-90"}],
        attachments=["attachment/5104320788332544"],
        rules=[{"reference": "Artigo 16, item (a)", "content": "pela assinatura isolada do Diretor Presidente", "signaturesRequired": 1, "eligibles": [{"name": "Daenerys Targaryen Stormborn", "taxId": "012.345.678-90", "role": "Diretor Presidente", "isSignatureRequired": True, "isRepresentative": True}]}],
        tags=["onboarding-123"],
        status="success",
        created="2026-06-12T12:00:00+00:00",
        updated="2026-06-12T12:10:00+00:00"
    )
]
```

### Get a Business Identity

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

Get a single business identity by its id. When `status=success`, the response includes the populated `rules` string with the signing combinations extracted by the AI Model.

**Parameters**

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

**Request**

```python
import starkinfra

identity = starkinfra.businessidentity.get("5740539971076096")
print(identity)
```

**Response**

```python
BusinessIdentity(
    id="5740539971076096",
    tax_id="20.018.183/0001-80",
    name="STARK BANK S.A.",
    tax_id_status="active",
    insight_tax_id="20.018.183/0001-80",
    insight_document_type="articles-of-incorporation",
    representatives=[{"name": "Daenerys Targaryen Stormborn", "qualification": "Diretor", "taxId": "012.345.678-90"}],
    attachments=["attachment/5104320788332544"],
    rules=[{"reference": "Artigo 16, item (a)", "content": "pela assinatura isolada do Diretor Presidente", "signaturesRequired": 1, "eligibles": [{"name": "Daenerys Targaryen Stormborn", "taxId": "012.345.678-90", "role": "Diretor Presidente", "isSignatureRequired": True, "isRepresentative": True}]}, {"reference": "Artigo 16, item (b)", "content": "pela assinatura de quaisquer 2 (dois) diretores em conjunto", "signaturesRequired": 2, "eligibles": [{"name": "Daenerys Targaryen Stormborn", "taxId": "012.345.678-90", "role": "Diretor Presidente", "isSignatureRequired": False, "isRepresentative": True}, {"name": "Jon Snow", "taxId": "098.765.432-10", "role": "Diretor de Riscos e Compliance", "isSignatureRequired": False, "isRepresentative": True}]}],
    tags=["onboarding-123"],
    status="success",
    created="2026-06-12T12:00:00+00:00",
    updated="2026-06-12T12:10:00+00:00"
)
```

### Update a Business Identity

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

Send a business identity to processing or replace its tags.

To trigger the AI Model analysis, set `status=processing`. The identity must be in `created`/`pending` status and must already have at least one Business Attachment associated with it.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the business identity entity. |
| `status` | OPTIONAL | Only `processing` is accepted. Triggers the AI Model analysis. |
| `tags` | OPTIONAL | Replace the current list of tags. |

**Request**

```python
import starkinfra

identity = starkinfra.businessidentity.update(
    id="5740539971076096",
    status="processing"
)

print(identity)
```

**Response**

```python
BusinessIdentity(
    id="5740539971076096",
    tax_id="20.018.183/0001-80",
    name="STARK BANK S.A.",
    tax_id_status="active",
    insight_tax_id="",
    insight_document_type="",
    representatives=[{"name": "Daenerys Targaryen Stormborn", "qualification": "Diretor", "taxId": "012.345.678-90"}],
    attachments=["attachment/5104320788332544"],
    rules=[],
    tags=["onboarding-123"],
    status="processing",
    created="2026-06-12T12:00:00+00:00",
    updated="2026-06-12T12:05:00+00:00"
)
```

### Cancel a Business Identity

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

Cancel a business identity. Only identities in `created` or `pending` status can be canceled.

**Parameters**

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

**Request**

```python
import starkinfra

identity = starkinfra.businessidentity.cancel("5740539971076096")
print(identity)
```

**Response**

```python
BusinessIdentity(
    id="5740539971076096",
    tax_id="20.018.183/0001-80",
    name="STARK BANK S.A.",
    tax_id_status="active",
    insight_tax_id="",
    insight_document_type="",
    representatives=[{"name": "Daenerys Targaryen Stormborn", "qualification": "Diretor", "taxId": "012.345.678-90"}],
    attachments=[],
    rules=[],
    tags=["onboarding-123"],
    status="canceled",
    created="2026-06-12T12:00:00+00:00",
    updated="2026-06-12T12:03:00+00:00"
)
```

### List Business Identity Logs

`GET /v2/business-identity/log`

Get a paged list of all business identity logs. A log tracks a change in the business 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 business identity ids linked to the desired logs. Max = 100. |
| `types` | OPTIONAL | Filter logs by log type. Options: "created", "updated", "processing", "canceled", "success", "failed". |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra

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

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

**Response**

```python
[
    BusinessIdentityLog(
        id="6248173092645824",
        type="success",
        identity=BusinessIdentity(id="5740539971076096", status="success"),
        errors=[],
        created="2026-06-12T12:10:00+00:00"
    )
]
```

### Get a Business Identity Log

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

Get a single business identity log by its id.

**Parameters**

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

**Request**

```python
import starkinfra

log = starkinfra.businessidentity.log.get("6248173092645824")
print(log)
```

**Response**

```python
BusinessIdentityLog(
    id="6248173092645824",
    type="success",
    identity=BusinessIdentity(id="5740539971076096", status="success"),
    errors=[],
    created="2026-06-12T12:10:00+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-identity-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/business-identity-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/business-identity-php.md)
- [Java](https://docs.starkinfra.com/api/v2/business-identity-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/business-identity-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/business-identity-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/business-identity-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/business-identity-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/business-identity-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/business-identity-curl.md)