Skip to content

Requests

These rules apply to every operation of /v1: how lists page, how a POST is retried safely, how many requests your application may send, how to name a request to support, and in which language errors answer.

Lists answer { data, has_more, next_cursor }, newest first. Pass next_cursor as cursor to read the next page; limit goes from 1 to 100 (25 by default). Cursors are opaque and only valid for the same list in the same organization; one whose last row was deleted answers invalid_cursor. The SDK pages for you (paginate); in PHP, a generator does it (PHP examples):

import {
function paginate<Input extends {
cursor?: string;
}, Item>(list: ListOperation<Input, Item>, input: Input): AsyncGenerator<Item, void, undefined>

Every item of a list, page after page: for await (const client of paginate(lexopti.clients.list, { limit: 100 })).

@yields ― {Item} Each item of each page, in the list's order.

paginate
} from "@lexopti/sdk";
for await (const
const client: {
id: string;
external_ref: string | null;
type: "person" | "company";
name: string;
person: {
first_name: string | null;
last_name: string | null;
usage_name: string | null;
birth_date: string | null;
birth_city: string | null;
birth_country: string | null;
nationalities: string[];
} | null;
company: {
name: string | null;
siren: string | null;
siret: string | null;
legal_form: string | null;
registration_country: string | null;
rcs: string | null;
} | null;
address: {
line: string | null;
postal_code: string | null;
city: string | null;
country: string | null;
};
... 10 more ...;
cases?: {
...;
} | undefined;
}
client
of
paginate<{
limit?: number | undefined;
cursor?: string | undefined;
external_ref?: string | undefined;
ids?: string | undefined;
expand?: ("cases" | "classification_state" | "last_check" | "open_alerts_count")[] | undefined;
}, {
id: string;
external_ref: string | null;
type: "person" | "company";
name: string;
person: {
first_name: string | null;
last_name: string | null;
usage_name: string | null;
birth_date: string | null;
birth_city: string | null;
birth_country: string | null;
nationalities: string[];
} | null;
company: {
name: string | null;
siren: string | null;
siret: string | null;
legal_form: string | null;
registration_country: string | null;
rcs: string | null;
} | null;
... 11 more ...;
cases?: {
...;
} | undefined;
}>(list: ListOperation<...>, input: {
limit?: number | undefined;
cursor?: string | undefined;
external_ref?: string | undefined;
ids?: string | undefined;
expand?: ("cases" | "classification_state" | "last_check" | "open_alerts_count")[] | undefined;
}): AsyncGenerator<...>

Every item of a list, page after page: for await (const client of paginate(lexopti.clients.list, { limit: 100 })).

@yields ― {Item} Each item of each page, in the list's order.

paginate
(
const lexopti: LexOptiClient
lexopti
.
clients: {
setExternalRef: Client<Record<never, never>, {
id: string;
external_ref: string;
}, {
id: string;
external_ref: string | null;
type: "person" | "company";
name: string;
person: {
first_name: string | null;
last_name: string | null;
usage_name: string | null;
birth_date: string | null;
birth_city: string | null;
birth_country: string | null;
nationalities: string[];
} | null;
company: {
name: string | null;
siren: string | null;
siret: string | null;
legal_form: string | null;
registration_country: string | null;
rcs: string | null;
} | null;
address: {
line: string | null;
postal_code: string | null;
city: string | null;
country: string | null;
};
... 10 more ...;
cases?: {
...;
} | undefined;
}, Error>;
... 7 more ...;
requestPreliminaryScreening: Client<...>;
}
clients
.
list: Client<Record<never, never>, {
limit?: number | undefined;
cursor?: string | undefined;
external_ref?: string | undefined;
ids?: string | undefined;
expand?: ("cases" | "classification_state" | "last_check" | "open_alerts_count")[] | undefined;
}, {
data: {
id: string;
external_ref: string | null;
type: "person" | "company";
name: string;
person: {
first_name: string | null;
last_name: string | null;
usage_name: string | null;
birth_date: string | null;
birth_city: string | null;
birth_country: string | null;
nationalities: string[];
} | null;
company: {
name: string | null;
siren: string | null;
siret: string | null;
legal_form: string | null;
registration_country: string | null;
rcs: string | null;
} | null;
address: {
line: string | null;
postal_code: string | null;
city: string | null;
country: string | null;
};
... 10 more ...;
cases?: {
...;
} | undefined;
}[];
has_more: boolean;
next_cursor: string | null;
}, Error>
list
, {
limit?: number | undefined
limit
: 100 })) {
var console: Console

The console module provides a simple debugging console that is similar to the JavaScript console mechanism provided by web browsers.

The module exports two specific components:

  • A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently synchronous like the browser APIs they resemble, nor are they consistently asynchronous like all other Node.js streams. See the note on process I/O for more information.

Example using the global console:

console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
// Error: Whoops, something bad happened
// at [eval]:5:15
// at Script.runInThisContext (node:vm:132:18)
// at Object.runInThisContext (node:vm:309:38)
// at node:internal/process/execution:77:19
// at [eval]-wrapper:6:22
// at evalScript (node:internal/process/execution:76:60)
// at node:internal/main/eval_string:23:3
const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr

Example using the Console class:

const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err

@see ― source

console
.
Console.log(message?: any, ...optionalParams: any[]): void (+1 overload)

Prints to stdout with newline. Multiple arguments can be passed, with the first used as the primary message and all additional used as substitution values similar to printf(3) (the arguments are all passed to util.format()).

const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout

See util.format() for more information.

@since ― v0.1.100

log
(
const client: {
id: string;
external_ref: string | null;
type: "person" | "company";
name: string;
person: {
first_name: string | null;
last_name: string | null;
usage_name: string | null;
birth_date: string | null;
birth_city: string | null;
birth_country: string | null;
nationalities: string[];
} | null;
company: {
name: string | null;
siren: string | null;
siret: string | null;
legal_form: string | null;
registration_country: string | null;
rcs: string | null;
} | null;
address: {
line: string | null;
postal_code: string | null;
city: string | null;
country: string | null;
};
... 10 more ...;
cases?: {
...;
} | undefined;
}
client
.
id: string
id
,
const client: {
id: string;
external_ref: string | null;
type: "person" | "company";
name: string;
person: {
first_name: string | null;
last_name: string | null;
usage_name: string | null;
birth_date: string | null;
birth_city: string | null;
birth_country: string | null;
nationalities: string[];
} | null;
company: {
name: string | null;
siren: string | null;
siret: string | null;
legal_form: string | null;
registration_country: string | null;
rcs: string | null;
} | null;
address: {
line: string | null;
postal_code: string | null;
city: string | null;
country: string | null;
};
... 10 more ...;
cases?: {
...;
} | undefined;
}
client
.
vigilance_level: "simplified" | "standard" | "enhanced" | null
vigilance_level
);
}

Your screens show LexOpti next to many of your records: read them in one request, keep them, and follow the webhooks for what changes. Never read LexOpti again for each page you draw (your own screens, by the API alone).

  • Several records in one filter. GET /v1/clients and GET /v1/cases take ids (LexOpti ids) and external_ref (your references), each a comma-separated list of 1 to 100 values: ?external_ref=crm:contact:1,crm:contact:2. GET /v1/alerts takes client_ids, the same list of client ids: ?client_ids=…&status=pending reads the pending alerts of a page of records. Both ids and external_ref together give the records both name. An unknown value is left out, as is a client of another organization or a reference of another application; more than 100 values, an empty one or a malformed one answers validation_failed. Ask limit=100 to read up to 100 records in one page.

  • What your screens show, with expand[]. As Stripe does, expand[] adds fields to each item, repeated once per field: ?expand[]=last_check&expand[]=cases. Send the brackets: a single expand=cases is refused (validation_failed), as Stripe refuses it; a field repeated counts once. The SDK takes an array (expand: ["last_check", "cases"]). For clients, GET /v1/clients and GET /v1/clients/{id}:

    • last_check: the client’s latest check (id, status, created_at, completed_at), null when none was launched;
    • open_alerts_count: its alerts awaiting a member’s review, those of its cases included;
    • classification_state: where its own classification stands (to_complete, in_progress, validated, revalidate);
    • cases: its 10 latest cases, main client or not (id, label, your external_ref, the validated risk_level, classification_state), with has_more.

    A field not asked is absent, not null. vigilance_level and the validated risk_level are always in the client. Expansions need no other scope than the list (lexopti:read), read only the organization of the token, and never carry the suspicion axis: the risk levels and classification states are the ones GET /v1/cases/{id}/classification scores without it.

  • What it costs. last_check, open_alerts_count and cases are one query each for the whole page (cases ranks each client’s cases in the database and keeps 11). classification_state composes each client’s classification, a few clients at a time. So a client read asking cases or classification_state counts in the rate limit for its page: 1 + ceil(clients × such expansions ÷ 25), the clients being limit (25 by default) for a list and 1 for GET /v1/clients/{id}. A page of 100 with both counts 9 requests; with last_check and open_alerts_count alone, 1.

  • Pagination. A cursor is bound to the list and its filters (ids, external_ref), not to expand[]: the next page of the same filters may ask other expansions.

POST /v1/clients, POST /v1/clients/{id}/preliminary-screening, POST /v1/cases, POST /v1/cases/{id}/checks, POST /v1/checks, POST /v1/members/enrolments, POST /v1/firms and POST /v1/webhook-endpoints require an Idempotency-Key header: a value unique to the request, 1 to 255 printable ASCII characters (a UUID, for example). A retry with the same key and body within 24 hours gets the first answer without running again; another body under the same key answers 422 idempotency_key_reused, a duplicate still running 409. A request that failed before doing anything frees its key; one that failed after creating its resource keeps it, and a retry gets 409 idempotency_response_unavailable naming the resource, to read with a GET. The answer of a webhook subscription carries its secret once: a retry gets 409 idempotency_secret_withheld, rotate the secret instead. The SDK adds a key to these POSTs and keeps it across its retries; it sends another operation again only after a 429 carrying Retry-After, which the API answers before running it (SDK). Sent by your own code, a key is drawn once per creation and kept across the retries of its request:

// The SDK draws the key, and sends it again with each retry of this call.
const
const client: {
id: string;
external_ref: string | null;
type: "person" | "company";
name: string;
person: {
first_name: string | null;
last_name: string | null;
usage_name: string | null;
birth_date: string | null;
birth_city: string | null;
birth_country: string | null;
nationalities: string[];
} | null;
company: {
name: string | null;
siren: string | null;
siret: string | null;
legal_form: string | null;
registration_country: string | null;
rcs: string | null;
} | null;
address: {
line: string | null;
postal_code: string | null;
city: string | null;
country: string | null;
};
... 10 more ...;
cases?: {
...;
} | undefined;
}
client
= await
const lexopti: LexOptiClient
lexopti
.
clients: {
setExternalRef: Client<Record<never, never>, {
id: string;
external_ref: string;
}, {
id: string;
external_ref: string | null;
type: "person" | "company";
name: string;
person: {
first_name: string | null;
last_name: string | null;
usage_name: string | null;
birth_date: string | null;
birth_city: string | null;
birth_country: string | null;
nationalities: string[];
} | null;
company: {
name: string | null;
siren: string | null;
siret: string | null;
legal_form: string | null;
registration_country: string | null;
rcs: string | null;
} | null;
address: {
line: string | null;
postal_code: string | null;
city: string | null;
country: string | null;
};
... 10 more ...;
cases?: {
...;
} | undefined;
}, Error>;
... 7 more ...;
requestPreliminaryScreening: Client<...>;
}
clients
.
create: Client
(input: {
type: "person";
person: {
first_name: string;
last_name: string;
usage_name?: string | undefined;
birth_date?: string | undefined;
birth_city?: string | undefined;
birth_country?: string | undefined;
nationalities?: string[] | undefined;
};
address?: {
line?: string | undefined;
postal_code?: string | undefined;
city?: string | undefined;
country?: string | undefined;
} | undefined;
external_ref?: string | undefined;
} | {
type: "company";
company: {
name: string;
siren?: string | undefined;
siret?: string | undefined;
legal_form?: string | undefined;
registration_country?: string | undefined;
rcs?: string | undefined;
};
address?: {
line?: string | undefined;
postal_code?: string | undefined;
city?: string | undefined;
country?: string | undefined;
} | undefined;
external_ref?: string | undefined;
}, options?: FriendlyClientOptions<...> | undefined) => ClientPromiseResult<...>
create
({
type: "person"
type
: "person",
person: {
first_name: string;
last_name: string;
usage_name?: string | undefined;
birth_date?: string | undefined;
birth_city?: string | undefined;
birth_country?: string | undefined;
nationalities?: string[] | undefined;
}
person
: {
first_name: string
first_name
: "Camille",
last_name: string
last_name
: "Durand" },
});
var console: Console

The console module provides a simple debugging console that is similar to the JavaScript console mechanism provided by web browsers.

The module exports two specific components:

  • A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently synchronous like the browser APIs they resemble, nor are they consistently asynchronous like all other Node.js streams. See the note on process I/O for more information.

Example using the global console:

console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
// Error: Whoops, something bad happened
// at [eval]:5:15
// at Script.runInThisContext (node:vm:132:18)
// at Object.runInThisContext (node:vm:309:38)
// at node:internal/process/execution:77:19
// at [eval]-wrapper:6:22
// at evalScript (node:internal/process/execution:76:60)
// at node:internal/main/eval_string:23:3
const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr

Example using the Console class:

const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err

@see ― source

console
.
Console.log(message?: any, ...optionalParams: any[]): void (+1 overload)

Prints to stdout with newline. Multiple arguments can be passed, with the first used as the primary message and all additional used as substitution values similar to printf(3) (the arguments are all passed to util.format()).

const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout

See util.format() for more information.

@since ― v0.1.100

log
(
const client: {
id: string;
external_ref: string | null;
type: "person" | "company";
name: string;
person: {
first_name: string | null;
last_name: string | null;
usage_name: string | null;
birth_date: string | null;
birth_city: string | null;
birth_country: string | null;
nationalities: string[];
} | null;
company: {
name: string | null;
siren: string | null;
siret: string | null;
legal_form: string | null;
registration_country: string | null;
rcs: string | null;
} | null;
address: {
line: string | null;
postal_code: string | null;
city: string | null;
country: string | null;
};
... 10 more ...;
cases?: {
...;
} | undefined;
}
client
.
id: string
id
);

1,000 requests per minute and application, across organizations; a client read with cases or classification_state counts for its page (read many records at once). Every answer to a request with a valid token carries RateLimit (remaining, seconds to reset) and RateLimit-Policy; a 429 carries Retry-After. Retry with exponential backoff and jitter; the SDK does it.

Every answer of /v1, success or error, carries a Request-Id header: req_ and 32 hexadecimal characters, generated by LexOpti for that request alone. A problem also carries it as its request_id member (errors); with the SDK, read problemOf(error)?.request_id. The id is opaque and holds nothing about the request; an id you send is ignored, never taken over. Browsers on an allowed origin can read it (Access-Control-Expose-Headers). Two answers come from the web server before the API sees the request, and carry no id: a body over 10 MiB (413) and the server’s own last-resort 500; quote the time and the operation instead.

Log it next to your own request, and quote it when you write to LexOpti support: it finds that request, its outcome and what it changed.

Accept-Language: fr gives French detail messages for the business errors, such as a client’s validation or an incomplete identity; the errors of the API itself (token, limits, idempotency, cursors) stay in English. code is always English.