Clients

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

Base
Mexico
Mexico AVI
Mexico JYS
Mexico TSC

With the base SDK, use nested scopeData format:

import { ClientType } from "@artu-ai/compliance-sdk";

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

With a Mexico-scoped SDK, fields are flattened to the root level:

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",
});

With an AVI-scoped SDK, both MX and AVI fields are flattened:

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
});

Creating Companies

Base
Mexico
Mexico AVI
Mexico JYS
Mexico TSC

const company = await sdk.clients.create({
  type: ClientType.Company,
  name: "Empresa Ejemplo S.A. de C.V.",
});

const company = await sdk.clients.create({
  type: ClientType.Company,
  name: "Empresa Ejemplo S.A. de C.V.",
  rfc: "EEJ200101XYZ",
  giroMercantil: GiroMercantil.ConstructionOther,
});

Retrieving Clients

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

Base
Mexico
Mexico AVI
Mexico JYS
Mexico TSC

const client = await sdk.clients.retrieve("client_abc123");

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

// 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"]

// Returns MexAVIClient with AVI-specific accessors
const client = await sdk.clients.retrieve("client_abc123");

console.log(client.rfc);      // "GALJ850101ABC"
console.log(client.username); // "JGARCIA"

// 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"

// 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"

Updating Clients

Base
Mexico
Mexico AVI
Mexico JYS
Mexico TSC

const updated = await sdk.clients.update("client_abc123", {
  name: "Juan García López Martínez",
});

const updated = await sdk.clients.update("client_abc123", {
  name: "Juan García López Martínez",
  actividadEconomica: ActividadEconomica.Architects,
});

const updated = await sdk.clients.update("client_abc123", {
  name: "Juan García López Martínez",
  username: "JGARCIA_NEW", // AVI-specific field
});

Listing Clients

Basic List

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

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

// 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);
}

Mexico-scoped SDKs automatically filter to clients with Mexico scope data.

Deleting Clients

await sdk.clients.delete("client_abc123");

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

Client Model Properties

Base
Mexico
Mexico AVI
Mexico JYS
Mexico TSC

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

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

Includes all Mexico properties plus:

Property	Type	Description
`username`	`string`	Platform username

Client Relationships

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

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

// 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

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

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

See Batch Operations for more details.

Getting Started

Core Resources

Patterns

Concepts

Client Types

Creating Clients

Creating Companies

Retrieving Clients

Accessing Scope Properties

Updating Clients

Listing Clients

Basic List

With Filtering

Async Iterator

Deleting Clients

Client Model Properties

Client Relationships

Batch Operations

Create Many

Partial Success Mode

Update Many

​Client Types

​Creating Clients

​Creating Companies

​Retrieving Clients

​Accessing Scope Properties

​Updating Clients

​Listing Clients

​Basic List

​With Filtering

​Async Iterator

​Deleting Clients

​Client Model Properties

​Client Relationships

​Batch Operations

​Create Many

​Partial Success Mode

​Update Many

Client Types

Creating Clients

Creating Companies

Retrieving Clients

Accessing Scope Properties

Updating Clients

Listing Clients

Basic List

With Filtering

Async Iterator

Deleting Clients

Client Model Properties

Client Relationships

Batch Operations

Create Many

Partial Success Mode

Update Many