# Business Attachment

BusinessAttachments are corporate documents (articles of incorporation, amendments, board minutes) uploaded against a Business Identity.

Each Business Identity accepts up to two attachments. The attachment goes through OCR and document validation; once both attachments are `approved`, the parent identity can be sent to `processing` to run the AI Model analysis.

### The BusinessAttachment object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the business attachment. |
| `name` | STRING | File name as provided on upload. Unique among the identity's other `created` attachments. |
| `businessIdentityId` | STRING | Id of the Business Identity that owns this attachment. |
| `attachmentId` | STRING | External attachment id in the document repository. Used internally to track approval. |
| `tags` | LIST OF STRINGS | Tags associated with the business attachment. |
| `status` | STRING | Current status of the attachment. Options: "created", "canceled", "approved", "denied". |
| `content` | STRING | Base64-encoded file content. Returned only when the GET request includes `expand=content`. |
| `created` | STRING | Creation datetime. Example: "2026-06-12T12:02:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2026-06-12T12:02:00.000000+00:00". |

### Upload a Business Attachment

`POST /v2/business-attachment`

Upload a single corporate document tied to a previously created Business Identity. Limit of **1 attachment per request** and **2 attachments per identity**.

**Validations:** only PDF, JPG and PNG are accepted, ≤ 8 MB per attachment; the `name` must be unique among the identity's other `created` attachments; the identity must be in `created`/`pending` status and have fewer than 2 attachments.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `name` | REQUIRED | File name. Must be unique among the identity's other `created` attachments. |
| `content` | REQUIRED | File payload encoded as a base64 string (e.g., `data:application/pdf;base64,...`). |
| `identityId` | REQUIRED | Id of the Business Identity that owns the attachment. |
| `tags` | OPTIONAL | List of strings to tag the entity for future queries. |

**Request**

```python
import starkinfra

attachments = starkinfra.businessattachment.create([
    starkinfra.BusinessAttachment(
        name="contrato-social.pdf",
        content="data:application/pdf;base64,JVBERi0xLjQK...",
        business_identity_id="5740539971076096",
        tags=["doc-principal"]
    )
])

for attachment in attachments:
    print(attachment)
```

**Response**

```python
[
    BusinessAttachment(
        id="6710539971076096",
        name="contrato-social.pdf",
        business_identity_id="5740539971076096",
        attachment_id="5104320788332544",
        tags=["doc-principal"],
        status="created",
        created="2026-06-12T12:02:00+00:00",
        updated="2026-06-12T12:02:00+00:00"
    )
]
```

### List Business Attachments

`GET /v2/business-attachment`

List and filter all business attachments in your workspace. Results are returned paged via cursor.

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

**Request**

```python
import starkinfra

attachments = starkinfra.businessattachment.query(
    after="2026-06-01",
    before="2026-06-30",
    status="approved",
    tags=["doc-principal"],
    limit=10
)

for attachment in attachments:
    print(attachment)
```

**Response**

```python
[
    BusinessAttachment(
        id="6710539971076096",
        name="contrato-social.pdf",
        business_identity_id="5740539971076096",
        attachment_id="5104320788332544",
        tags=["doc-principal"],
        status="approved",
        created="2026-06-12T12:02:00+00:00",
        updated="2026-06-12T12:08:00+00:00"
    )
]
```

### Get a Business Attachment

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

Get a single business attachment by its id. Pass `expand=content` to include the base64 file payload in the response.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the business attachment entity. |
| `expand` | OPTIONAL | List of fields to expand. Currently only `content` is supported — when present, the response includes the base64-encoded file payload. |

**Request**

```python
import starkinfra

attachment = starkinfra.businessattachment.get(
    "6710539971076096",
    expand=["content"]
)

print(attachment)
```

**Response**

```python
BusinessAttachment(
    id="6710539971076096",
    name="contrato-social.pdf",
    business_identity_id="5740539971076096",
    attachment_id="5104320788332544",
    tags=["doc-principal"],
    status="approved",
    content="data:application/pdf;base64,JVBERi0xLjQK...",
    created="2026-06-12T12:02:00+00:00",
    updated="2026-06-12T12:08:00+00:00"
)
```

### Cancel a Business Attachment

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

Cancel a business attachment. Only attachments in `created` status can be canceled.

**Parameters**

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

**Request**

```python
import starkinfra

attachment = starkinfra.businessattachment.cancel("6710539971076096")
print(attachment)
```

**Response**

```python
BusinessAttachment(
    id="6710539971076096",
    name="contrato-social.pdf",
    business_identity_id="5740539971076096",
    attachment_id="5104320788332544",
    tags=["doc-principal"],
    status="canceled",
    created="2026-06-12T12:02:00+00:00",
    updated="2026-06-12T12:03:30+00:00"
)
```

### List Business Attachment Logs

`GET /v2/business-attachment/log`

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

**Request**

```python
import starkinfra

logs = starkinfra.businessattachment.log.query(
    types=["approved", "denied"],
    attachment_ids=["6710539971076096"],
    limit=10
)

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

**Response**

```python
[
    BusinessAttachmentLog(
        id="5719045286731328",
        type="approved",
        attachment=BusinessAttachment(id="6710539971076096", status="approved"),
        errors=[],
        created="2026-06-12T12:08:00+00:00"
    )
]
```

### Get a Business Attachment Log

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

Get a single business attachment log by its id.

**Parameters**

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

**Request**

```python
import starkinfra

log = starkinfra.businessattachment.log.get("5719045286731328")
print(log)
```

**Response**

```python
BusinessAttachmentLog(
    id="5719045286731328",
    type="approved",
    attachment=BusinessAttachment(id="6710539971076096", status="approved"),
    errors=[],
    created="2026-06-12T12:08: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-attachment-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/business-attachment-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/business-attachment-php.md)
- [Java](https://docs.starkinfra.com/api/v2/business-attachment-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/business-attachment-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/business-attachment-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/business-attachment-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/business-attachment-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/business-attachment-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/business-attachment-curl.md)