> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Documents

> Upload and manage client documents

Documents store identification and verification files for clients.

## Creating Document Records

Documents are created in two steps: create the record, then upload the file.

```typescript theme={null}
import { DocumentCategory } from "@artu-ai/compliance-sdk";

const doc = await sdk.documents.create({
  clientId: "client_abc123",
  scope: "MX",
  type: "ine_front",
  category: DocumentCategory.Identity,
});

console.log(doc.id);
console.log(doc.status); // "pending_upload"
```

## Document Categories

| Category    | Description                                    |
| ----------- | ---------------------------------------------- |
| `Identity`  | Identity documents (INE, passport)             |
| `Address`   | Proof of address                               |
| `Financial` | Financial statements, tax records              |
| `Legal`     | Legal documents (powers of attorney, articles) |
| `Other`     | Other document types                           |

## Document Types

<Tabs>
  <Tab title="Mexico">
    | Type                | Enum                               | Description               |
    | ------------------- | ---------------------------------- | ------------------------- |
    | `ine_front`         | `MexDocumentType.IneFront`         | INE (voter ID) front      |
    | `ine_back`          | `MexDocumentType.IneBack`          | INE (voter ID) back       |
    | `passport`          | `MexDocumentType.Passport`         | Passport                  |
    | `curp`              | `MexDocumentType.Curp`             | CURP document             |
    | `rfc_constancia`    | `MexDocumentType.RfcConstancia`    | RFC certificate           |
    | `declaracion_anual` | `MexDocumentType.DeclaracionAnual` | Annual tax declaration    |
    | `address_proof`     | `MexDocumentType.AddressProof`     | Proof of address          |
    | `acta_constitutiva` | `MexDocumentType.ActaConstitutiva` | Articles of incorporation |
    | `poder_notarial`    | `MexDocumentType.PoderNotarial`    | Power of attorney         |
    | `other`             | `MexDocumentType.Other`            | Other document type       |

    ```typescript theme={null}
    import { MexDocumentType } from "@artu-ai/shared";

    const doc = await sdk.documents.create({
      clientId: "client_abc123",
      scope: "MX",
      type: MexDocumentType.IneFront,
      category: DocumentCategory.Identity,
    });
    ```
  </Tab>
</Tabs>

## Retrieving Documents

```typescript theme={null}
const doc = await sdk.documents.retrieve("doc_xyz789");

console.log(doc.id);
console.log(doc.type);
console.log(doc.status);
console.log(doc.isAvailable);
```

Need to search by your own IDs or metadata? Use `retrieveByExternalId` or `retrieveByMetadata` (see [SDK reference](/sdk/resources)).

## Updating Documents

```typescript theme={null}
const updated = await sdk.documents.update("doc_xyz789", {
  expiresAt: new Date("2030-01-01"),
  metadata: {
    verified: true,
    verifiedBy: "admin@example.com",
  },
});
```

## Listing Documents

### All Documents

```typescript theme={null}
const { data } = await sdk.documents.list({
  limit: 50,
});
```

### By Client

```typescript theme={null}
const { data } = await sdk.documents.listByClient("client_abc123");
```

### By Type

```typescript theme={null}
const { data } = await sdk.documents.list({
  filter: {
    clientId: "client_abc123",
    type: "ine_front",
  },
});
```

### Async Iterator

```typescript theme={null}
for await (const doc of sdk.documents.iterate()) {
  console.log(doc.id, doc.type);
}
```

## Document Status

| Status           | Description                          |
| ---------------- | ------------------------------------ |
| `pending_upload` | Record created, awaiting file upload |
| `processing`     | File uploaded, being processed       |
| `available`      | Document is available                |
| `failed`         | Processing failed                    |
| `expired`        | Document has expired                 |

## Checking Document Existence

```typescript theme={null}
// Check if a specific document type exists for a client
const hasINE = await sdk.documents.hasDocumentType(
  "client_abc123",
  "ine_front",
);

if (!hasINE) {
  console.log("Client needs to upload INE front");
}
```

## Counting Documents

```typescript theme={null}
const count = await sdk.documents.countByClient("client_abc123");
console.log(`Client has ${count} documents`);
```

## Deleting Documents

```typescript theme={null}
await sdk.documents.delete("doc_xyz789");
```

## Document Model Properties

| Property      | Type                  | Description           |
| ------------- | --------------------- | --------------------- |
| `id`          | `string`              | Unique identifier     |
| `clientId`    | `string`              | Parent client ID      |
| `type`        | `string`              | Document type         |
| `category`    | `DocumentCategory`    | Document category     |
| `scope`       | `string`              | Scope code            |
| `status`      | `DocumentStatus`      | Current status        |
| `isAvailable` | `boolean`             | True if available     |
| `filename`    | `string \| undefined` | Original filename     |
| `mimeType`    | `string \| undefined` | File MIME type        |
| `size`        | `number \| undefined` | File size in bytes    |
| `expiresAt`   | `Date \| undefined`   | Expiration date       |
| `metadata`    | `object \| undefined` | Custom metadata       |
| `createdAt`   | `Date`                | Creation timestamp    |
| `updatedAt`   | `Date`                | Last update timestamp |

## Batch Operations

Create multiple document records:

```typescript theme={null}
const result = await sdk.documents.createMany([
  { clientId, type: "ine_front", category: DocumentCategory.Identity, ... },
  { clientId, type: "ine_back", category: DocumentCategory.Identity, ... },
]);
```

## Mexico Document Fields

Mexico documents can include extracted field data:

```typescript theme={null}
import { isIneFront, isRfcConstancia } from "@artu-ai/compliance-sdk/mx";

const doc = await sdk.documents.retrieve("doc_xyz789");

if (isIneFront(doc)) {
  // Access INE-specific fields
  console.log(doc.fields.cic);
  console.log(doc.fields.ocr);
  console.log(doc.fields.claveElector);
  console.log(doc.fields.seccion);
}

if (isRfcConstancia(doc)) {
  // Access RFC constancia fields
  console.log(doc.fields.rfc);
  console.log(doc.fields.regimenFiscal);
}
```

<Info>
  See [Mexico Scope](/scopes/mexico) for all document type
  guards.
</Info>