> ## 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.

# Clients

> Create and manage client records

Clients represent the individuals, companies, or trusts you need to track for compliance purposes.

## Client Types

| Type         | Description        | Example                              |
| ------------ | ------------------ | ------------------------------------ |
| `Individual` | Natural individual | A customer, employee, or beneficiary |
| `Company`    | Legal entity       | A corporation, LLC, or partnership   |
| `Trust`      | Trust structure    | A family trust or foundation         |

## Creating Clients

<Tabs>
  <Tab title="Base">
    With the base SDK, use nested `scopeData` format:

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

    const individual = await sdk.clients.create({
      type: ClientType.Individual,
      name: "Juan García López",
      nationalities: ["MX"],
    });
    ```
  </Tab>

  <Tab title="Mexico">
    With a Mexico-scoped SDK, fields are flattened to the root level:

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

    // MX fields at root level - no nested scopeData needed
    const individual = await sdk.clients.create({
      type: ClientType.Individual,
      name: "Juan García López",
      nationalities: ["MX"],
      rfc: "GALJ850101ABC",
      curp: "GALJ850101HDFRRL09",
    });

    ```
  </Tab>

  <Tab title="Mexico AVI">
    With an AVI-scoped SDK, both MX and AVI fields are flattened:

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

    // AVI fields at root level
    const aviClient = await sdk.clients.create({
      type: ClientType.Individual,
      name: "Juan García López",
      nationalities: ["MX"],
      rfc: "GALJ850101ABC",
      curp: "GALJ850101HDFRRL09",
      username: "JGARCIA", // AVI-specific field
    });
    ```
  </Tab>

  <Tab title="Mexico JYS">
    Same as Mexico. JYS clients use Mexico-scoped input with no additional fields.
  </Tab>

  <Tab title="Mexico TSC">
    Same as Mexico. TSC clients use Mexico-scoped input with no additional fields.
  </Tab>
</Tabs>

### Creating Companies

<Tabs>
  <Tab title="Base">
    ```typescript theme={null}
    const company = await sdk.clients.create({
      type: ClientType.Company,
      name: "Empresa Ejemplo S.A. de C.V.",
    });
    ```
  </Tab>

  <Tab title="Mexico">
    ```typescript theme={null}
    const company = await sdk.clients.create({
      type: ClientType.Company,
      name: "Empresa Ejemplo S.A. de C.V.",
      rfc: "EEJ200101XYZ",
      giroMercantil: GiroMercantil.ConstructionOther,
    });
    ```
  </Tab>

  <Tab title="Mexico AVI">
    Same as Mexico for companies.
  </Tab>

  <Tab title="Mexico JYS">
    Same as Mexico for companies.
  </Tab>

  <Tab title="Mexico TSC">
    Same as Mexico for companies.
  </Tab>
</Tabs>

## Retrieving Clients

```typescript theme={null}
const client = await sdk.clients.retrieve("client_abc123");

console.log(client.id);
console.log(client.name);
console.log(client.type);
console.log(client.createdAt);
```

### Accessing Scope Properties

<Tabs>
  <Tab title="Base">
    ```typescript theme={null}
    const client = await sdk.clients.retrieve("client_abc123");

    // Check scope and access raw data
    if (client.hasScope("MX")) {
      console.log(client.scopeData.MX?.rfc);
    }
    ```
  </Tab>

  <Tab title="Mexico">
    ```typescript theme={null}
    // Returns MexClient with typed accessors
    const client = await sdk.clients.retrieve("client_abc123");

    console.log(client.rfc);                // "GALJ850101ABC"
    console.log(client.curp);               // "GALJ850101HDFRRL09"
    console.log(client.actividadEconomica); // "4611"
    console.log(client.giroMercantil);      // "Comercio al por mayor"
    console.log(client.isActividadVulnerable); // true/false
    console.log(client.activityCodes);      // ["AVI", "JYS"]
    ```
  </Tab>

  <Tab title="Mexico AVI">
    ```typescript theme={null}
    // Returns MexAVIClient with AVI-specific accessors
    const client = await sdk.clients.retrieve("client_abc123");

    console.log(client.rfc);      // "GALJ850101ABC"
    console.log(client.username); // "JGARCIA"
    ```
  </Tab>

  <Tab title="Mexico JYS">
    ```typescript theme={null}
    // Returns MexJYSClient with same accessors as MexClient
    const client = await sdk.clients.retrieve("client_abc123");

    console.log(client.rfc);  // "GALJ850101ABC"
    console.log(client.curp); // "GALJ850101HDFRRL09"
    ```
  </Tab>

  <Tab title="Mexico TSC">
    ```typescript theme={null}
    // Returns MexTSCClient with same accessors as MexClient
    const client = await sdk.clients.retrieve("client_abc123");

    console.log(client.rfc);  // "GALJ850101ABC"
    console.log(client.curp); // "GALJ850101HDFRRL09"
    ```
  </Tab>
</Tabs>

## Updating Clients

<Tabs>
  <Tab title="Base">
    ```typescript theme={null}
    const updated = await sdk.clients.update("client_abc123", {
      name: "Juan García López Martínez",
    });
    ```
  </Tab>

  <Tab title="Mexico">
    ```typescript theme={null}
    const updated = await sdk.clients.update("client_abc123", {
      name: "Juan García López Martínez",
      actividadEconomica: ActividadEconomica.Architects,
    });
    ```
  </Tab>

  <Tab title="Mexico AVI">
    ```typescript theme={null}
    const updated = await sdk.clients.update("client_abc123", {
      name: "Juan García López Martínez",
      username: "JGARCIA_NEW", // AVI-specific field
    });
    ```
  </Tab>

  <Tab title="Mexico JYS">
    Same as Mexico for updates.
  </Tab>

  <Tab title="Mexico TSC">
    Same as Mexico for updates.
  </Tab>
</Tabs>

## Listing Clients

### Basic List

```typescript theme={null}
const { data, pagination } = await sdk.clients.list({
  limit: 20,
});

for (const client of data) {
  console.log(client.name);
}

// Check for more pages
if (pagination.hasMore) {
  const nextPage = await sdk.clients.list({
    cursor: pagination.nextCursor,
  });
}
```

### With Filtering

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

const { data } = await sdk.clients.list({
  filter: {
    type: oneOf("individual", "company"),
    name: contains("García"),
  },
  limit: 50,
});
```

### Async Iterator

```typescript theme={null}
// Automatically handles pagination
for await (const client of sdk.clients.iterate()) {
  console.log(client.name);
}

// With filter
for await (const client of sdk.clients.iterate({ type: "individual" })) {
  await processClient(client);
}
```

<Info>
  Mexico-scoped SDKs automatically filter to clients with Mexico scope
  data.
</Info>

## Deleting Clients

```typescript theme={null}
await sdk.clients.delete("client_abc123");
```

<Warning>
  Deletion is a soft delete. The client record is marked as deleted but retained
  for audit purposes.
</Warning>

## Client Model Properties

<Tabs>
  <Tab title="Base">
    | Property            | Type                    | Description                    |
    | ------------------- | ----------------------- | ------------------------------ |
    | `id`                | `string`                | Unique identifier              |
    | `type`              | `ClientType`            | Client type                    |
    | `name`              | `string`                | Full legal name                |
    | `isIndividual`      | `boolean`               | True if individual             |
    | `isCompany`         | `boolean`               | True if company                |
    | `isTrust`           | `boolean`               | True if trust                  |
    | `nationalities`     | `string[]`              | Nationality codes              |
    | `birthDate`         | `Date \| undefined`     | Birth date (individuals)       |
    | `middleName`        | `string \| undefined`   | Middle name (individuals)      |
    | `lastName`          | `string[] \| undefined` | Last name(s) (individuals)     |
    | `incorporationDate` | `Date \| undefined`     | Incorporation date (companies) |
    | `formationDate`     | `Date \| undefined`     | Formation date (trusts)        |
    | `externalId`        | `string \| undefined`   | Your system's ID               |
    | `metadata`          | `object \| undefined`   | Custom metadata                |
    | `createdAt`         | `Date`                  | Creation timestamp             |
    | `updatedAt`         | `Date`                  | Last update timestamp          |
  </Tab>

  <Tab title="Mexico">
    Includes all base properties plus:

    | Property                | Type       | Description                      |
    | ----------------------- | ---------- | -------------------------------- |
    | `rfc`                   | `string`   | Tax ID (RFC)                     |
    | `curp`                  | `string`   | National ID (CURP) - individuals |
    | `actividadEconomica`    | `string`   | Economic activity code           |
    | `giroMercantil`         | `string`   | Business sector                  |
    | `isActividadVulnerable` | `boolean`  | Has vulnerable activity data     |
    | `activityCodes`         | `string[]` | Registered activity codes        |
    | `hasActivity(code)`     | `boolean`  | Check if registered for activity |
  </Tab>

  <Tab title="Mexico AVI">
    Includes all Mexico properties plus:

    | Property   | Type     | Description       |
    | ---------- | -------- | ----------------- |
    | `username` | `string` | Platform username |
  </Tab>

  <Tab title="Mexico JYS">
    Same properties as Mexico. JYS (Juegos y Sorteos) clients don't have additional client-level properties.
  </Tab>

  <Tab title="Mexico TSC">
    Same properties as Mexico. TSC (Tarjetas de Servicio y Crédito) clients don't have additional client-level properties.
  </Tab>
</Tabs>

## Client Relationships

Link clients together to represent relationships like legal representatives or beneficiaries:

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

// Link a legal representative to a company
await sdk.clients.linkClient(
  companyId,
  legalRepId,
  ClientRelationshipType.LegalRepresentative,
);

// Link with metadata
await sdk.clients.linkClient(
  companyId,
  beneficiaryId,
  ClientRelationshipType.ControllingBeneficiary,
  { ownershipPercentage: 51 },
);

// List linked clients
const links = await sdk.clients.listLinkedClients(companyId);

// Filter by relationship type
const legalReps = await sdk.clients.listLinkedClients(
  companyId,
  ClientRelationshipType.LegalRepresentative,
);

// Unlink a client
await sdk.clients.unlinkClient(
  companyId,
  legalRepId,
  ClientRelationshipType.LegalRepresentative,
);

// Replace all linked clients
await sdk.clients.setLinkedClients(companyId, [
  { clientId: legalRepId, relationshipType: "legal_representative" },
  { clientId: beneficiaryId, relationshipType: "controlling_beneficiary" },
]);
```

## Batch Operations

### Create Many

```typescript theme={null}
// Atomic mode (default) - all succeed or all fail
const result = await sdk.clients.createMany([
  { type: ClientType.Individual, name: "Juan García", ... },
  { type: ClientType.Individual, name: "María López", ... },
]);

if (result.atomic) {
  console.log("All clients created:", result.data.length);
}
```

### Partial Success Mode

```typescript theme={null}
const result = await sdk.clients.createMany(clients, { atomic: false });

if (!result.atomic) {
  console.log("Succeeded:", result.succeeded.length);
  console.log("Failed:", result.failed.length);

  for (const failure of result.failed) {
    console.log(`Index ${failure.index}: ${failure.error.message}`);
  }
}
```

### Update Many

```typescript theme={null}
const result = await sdk.clients.updateMany([
  { id: "client_1", data: { name: "Updated Name 1" } },
  { id: "client_2", data: { name: "Updated Name 2" } },
]);
```

<Info>See [Batch Operations](/guides/batch-operations) for more details.</Info>