This guide builds a complete integration in your own software, in the order a partner builds it: connect a member, link your records to LexOpti clients, launch checks, embed LexOpti’s screens, receive webhooks, and disconnect. It assumes you did the quickstart. LexOpti’s reference CRM runs this journey in its tests; the pitfalls flagged below are the ones it surfaced.
Your software can show LexOpti in two ways, and combine them. Both start the same way, with the member’s connection (step 2) and your records linked to LexOpti clients (step 3); they differ in who draws the screens.
The API alone. Your server reads LexOpti through /v1 with the member’s token and your own screens show it: each client’s vigilance level, its last check, its cases, its alerts to review, where its classification stands, the report to download (your own screens, by the API alone). No iframe, no LexOpti script in your pages.
Embedded components. LexOpti’s real screens (client, case, new client, new case, the whole application) in your pages, through custom elements that drive an iframe (step 5, embedded components). The member works in LexOpti without leaving your software.
Both. Your screens for the summary next to your record (level, alerts, report), and the embedded screens for what only the member can do.
API alone
Embedded components
Both
Effort on your side
Higher: you design, build and maintain each screen, its states and its translations
Lower: a tag, the script and a session provider; LexOpti’s screens evolve without you
The sum, but each screen where it fits best
Who owns the interface
You, entirely: your design system, your words, your layout
LexOpti, inside a frame in your page; you choose its display (inline, panel, fullscreen) and a few theme variables
You for the summary, LexOpti for the compliance work
Compliance screens only the member fills
Not available: the TRACFIN classification is read only through the API, never answered nor validated, and the suspicion axis is never returned. The member fills them in LexOpti itself (deep link)
In your page: the classification questionnaire, its validation, the suspicion axis the member sees as in LexOpti
In your page, through the components
Mobile
Your native screens on any device; your server keeps the tokens
Native summary, webview for the compliance screens
White label
Complete: LexOpti never appears, except where you name it
LexOpti’s screens, framed in your page
Your brand on your screens, LexOpti’s inside the components
Prefer the API alone when you need your own interface everywhere (a white-label product, a native mobile app, an existing design system) and your members can complete the classification in LexOpti. Prefer the embedded components to ship quickly, or when the member must do the compliance work (classification, validation, review in context) without leaving your software.
LexOpti registers your application: a confidential client (its secret stays on your server), its exact redirect URIs and, for the embedded components, the origins of the pages that show them. You get a sandbox organization to develop against, provisioned for your LexOpti account: deterministic screening, no billing. Developer and professional accounts are separate: if you already use LexOpti as a professional, give LexOpti another e-mail address for development.
A redirect URI is HTTPS, also during development: http://localhost is refused for a web application. Serve your local app on a *.localhost name with a locally trusted certificate (for example https://crm.localhost:4400 with mkcert), or through an HTTPS tunnel, and register that URI.
OAuth 2.1, authorization code with PKCE (S256). Your server keeps the verifier, binds the state to the browser (a cookie), and sends the member to LexOpti:
Creates and returns a Hash object that can be used to generate hash digests
using the given algorithm. Optional options argument controls stream
behavior. For XOF hash functions such as 'shake256', the outputLength option
can be used to specify the desired output length in bytes.
The algorithm is dependent on the available algorithms supported by the
version of OpenSSL on the platform. Examples are 'sha256', 'sha512', etc.
On recent releases of OpenSSL, openssl list -digest-algorithms will
display the available digest algorithms.
Example: generating the sha256 sum of a file
import {
createReadStream,
} from'node:fs';
import { argv } from'node:process';
const {
createHash,
} = await import('node:crypto');
const filename = argv[2];
const hash = createHash('sha256');
const input = createReadStream(filename);
input.on('readable', ()=> {
// Only one element is going to be produced by the
Generates cryptographically strong pseudorandom data. The size argument
is a number indicating the number of bytes to generate.
If a callback function is provided, the bytes are generated asynchronously
and the callback function is invoked with two arguments: err and buf.
If an error occurs, err will be an Error object; otherwise it is null. The buf argument is a Buffer containing the generated bytes.
// Asynchronous
const {
randomBytes,
} = await import('node:crypto');
randomBytes(256, (err, buf)=> {
if (err) throwerr;
console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`);
});
If the callback function is not provided, the random bytes are generated
synchronously and returned as a Buffer. An error will be thrown if
there is a problem generating the bytes.
// Synchronous
const {
randomBytes,
} = await import('node:crypto');
const buf = randomBytes(256);
console.log(
`${buf.length} bytes of random data: ${buf.toString('hex')}`);
The crypto.randomBytes() method will not complete until there is
sufficient entropy available.
This should normally never take longer than a few milliseconds. The only time
when generating the random bytes may conceivably block for a longer period of
time is right after boot, when the whole system is still low on entropy.
This API uses libuv's threadpool, which can have surprising and
negative performance implications for some applications; see the UV_THREADPOOL_SIZE documentation for more information.
The asynchronous version of crypto.randomBytes() is carried out in a single
threadpool request. To minimize threadpool task length variation, partition
large randomBytes requests when doing so as part of fulfilling a client
request.
@since ― v0.5.8
@param ― size The number of bytes to generate. The size must not be larger than 2**31 - 1.
@return ― if the callback function is not provided.
Generates cryptographically strong pseudorandom data. The size argument
is a number indicating the number of bytes to generate.
If a callback function is provided, the bytes are generated asynchronously
and the callback function is invoked with two arguments: err and buf.
If an error occurs, err will be an Error object; otherwise it is null. The buf argument is a Buffer containing the generated bytes.
// Asynchronous
const {
randomBytes,
} = await import('node:crypto');
randomBytes(256, (err, buf)=> {
if (err) throwerr;
console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`);
});
If the callback function is not provided, the random bytes are generated
synchronously and returned as a Buffer. An error will be thrown if
there is a problem generating the bytes.
// Synchronous
const {
randomBytes,
} = await import('node:crypto');
const buf = randomBytes(256);
console.log(
`${buf.length} bytes of random data: ${buf.toString('hex')}`);
The crypto.randomBytes() method will not complete until there is
sufficient entropy available.
This should normally never take longer than a few milliseconds. The only time
when generating the random bytes may conceivably block for a longer period of
time is right after boot, when the whole system is still low on entropy.
This API uses libuv's threadpool, which can have surprising and
negative performance implications for some applications; see the UV_THREADPOOL_SIZE documentation for more information.
The asynchronous version of crypto.randomBytes() is carried out in a single
threadpool request. To minimize threadpool task length variation, partition
large randomBytes requests when doing so as part of fulfilling a client
request.
@since ― v0.5.8
@param ― size The number of bytes to generate. The size must not be larger than 2**31 - 1.
@return ― if the callback function is not provided.
Generates cryptographically strong pseudorandom data. The size argument
is a number indicating the number of bytes to generate.
If a callback function is provided, the bytes are generated asynchronously
and the callback function is invoked with two arguments: err and buf.
If an error occurs, err will be an Error object; otherwise it is null. The buf argument is a Buffer containing the generated bytes.
// Asynchronous
const {
randomBytes,
} = await import('node:crypto');
randomBytes(256, (err, buf)=> {
if (err) throwerr;
console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`);
});
If the callback function is not provided, the random bytes are generated
synchronously and returned as a Buffer. An error will be thrown if
there is a problem generating the bytes.
// Synchronous
const {
randomBytes,
} = await import('node:crypto');
const buf = randomBytes(256);
console.log(
`${buf.length} bytes of random data: ${buf.toString('hex')}`);
The crypto.randomBytes() method will not complete until there is
sufficient entropy available.
This should normally never take longer than a few milliseconds. The only time
when generating the random bytes may conceivably block for a longer period of
time is right after boot, when the whole system is still low on entropy.
This API uses libuv's threadpool, which can have surprising and
negative performance implications for some applications; see the UV_THREADPOOL_SIZE documentation for more information.
The asynchronous version of crypto.randomBytes() is carried out in a single
threadpool request. To minimize threadpool task length variation, partition
large randomBytes requests when doing so as part of fulfilling a client
request.
@since ― v0.5.8
@param ― size The number of bytes to generate. The size must not be larger than 2**31 - 1.
@return ― if the callback function is not provided.
The search property of the URL interface is a search string, also called a query string, that is a string containing a '?' followed by the parameters of the URL.
Creates and returns a Hash object that can be used to generate hash digests
using the given algorithm. Optional options argument controls stream
behavior. For XOF hash functions such as 'shake256', the outputLength option
can be used to specify the desired output length in bytes.
The algorithm is dependent on the available algorithms supported by the
version of OpenSSL on the platform. Examples are 'sha256', 'sha512', etc.
On recent releases of OpenSSL, openssl list -digest-algorithms will
display the available digest algorithms.
Example: generating the sha256 sum of a file
import {
createReadStream,
} from'node:fs';
import { argv } from'node:process';
const {
createHash,
} = await import('node:crypto');
const filename = argv[2];
const hash = createHash('sha256');
const input = createReadStream(filename);
input.on('readable', ()=> {
// Only one element is going to be produced by the
// hash stream.
const data = input.read();
if (data)
hash.update(data);
else {
console.log(`${hash.digest('hex')}${filename}`);
}
});
@since ― v0.1.92
@param ― options stream.transform options
createHash("sha256").
Hash.update(data: BinaryLike): Hash (+1 overload)
Updates the hash content with the given data, the encoding of which
is given in inputEncoding.
If encoding is not provided, and the data is a string, an
encoding of 'utf8' is enforced. If data is a Buffer, TypedArray, orDataView, then inputEncoding is ignored.
This can be called many times with new data as it is streamed.
@since ― v0.1.92
@param ― inputEncoding The encoding of the data string.
Calculates the digest of all of the data passed to be hashed (using the hash.update() method).
If encoding is provided a string will be returned; otherwise
a Buffer is returned.
The Hash object can not be used again after hash.digest() method has been
called. Multiple calls will cause an error to be thrown.
@since ― v0.1.92
@param ― encoding The encoding of the return value.
Your software already knows the member and their organization: give them to LexOpti in the lexopti_hint parameter of the authorization request, and the sign-in starts with their address, the sign-up with their name, organization and SIREN. Hints, never facts: every field stays theirs to change, they attest their own organization, and the address is still verified by the code sent. The SIREN is prefilled but never locked; if they pick another one, LexOpti warns them and offers to join the existing organization when that SIREN is already a client.
The lexopti_hint value for an authorization request: the hint as JSON,
base64url. Throws when the hint is not valid or too large, so a partner
finds out while developing, not the member while signing up.
Accepted fields: email, given_name, family_name, firm.name, firm.siren (nine digits), firm.profession (lawyer, notary, accountant, real_estate, other_regulated), firm.phone (E.164), firm.address.{line1, postal_code, city}; 2 KB at most once encoded. An invalid field drops the whole hint (an unknown firm.profession is only left out), never blocks the sign-in. With lexopti_claim (section 14), the prepared organization wins over the hint.
The member signs in, picks the organization (their sandbox while you develop) and consents. Your callback checks that the returned state is the browser’s, then exchanges the code with HTTP Basic authentication:
Make the callback idempotent: a browser may request it twice (a navigation retried while you exchange the code). The second request must wait for the first one’s result, never exchange the code again, and never show an error. Access tokens live 15 minutes: before they expire, call the token endpoint with grant_type=refresh_token, the refresh token and the resource, and store the new refresh token it answers, which replaces the old one (authentication; with the SDK, provide and refresh the token). Refresh one request at a time, so that two never use the same refresh token: a shared promise in a Node.js server, an exclusive lock between PHP workers.
Link each record idempotently, by your own id: give the LexOpti client your record’s external_ref, an opaque technical id such as crm:contact:1042 (never a name, a birth date or an e-mail). Look the client up by that reference first, create it with the reference only when none has it, and reuse the client the reference names on every later link. A retried request, a second click, a restart of your server or a lost local link then never creates a second client for the same record.
A typed client of the LexOpti API. Every idempotent POST gets an
Idempotency-Key (kept across its retries); only requests safe to repeat
are retried after a failure, with jittered backoff or Retry-After. Errors are oRPC errors: problemOf(error) reads the
problem details.
The problem details (RFC 9457) of a failed call: code is stable,
branch on it; request_id names the request for LexOpti support; null
for an error that did not come from the API.
# None: create the client with the reference. A 409 external_ref_conflict
# means another request linked it meanwhile: look it up again.
curlhttps://app.lexopti.com/v1/clients\
-H"Authorization: Bearer $LEXOPTI_ACCESS_TOKEN"\
-H"Idempotency-Key: $(uuidgen)"\
--json'{
"type": "person",
"person": {
"first_name": "Camille",
"last_name": "Durand",
"birth_date": "1984-03-12",
"nationalities": ["FR"]
},
"external_ref": "crm:contact:1042"
}'
The lookup answers at most one client of your application (an unknown reference gives an empty page). A creation whose reference already names a client, for example when two requests link the same record at once, is refused as a whole: 409, a problem whose code is external_ref_conflict. The client is not created, and the problem does not carry the existing client’s id: read it with GET /v1/clients?external_ref=…, as the catch above does.
You may keep the LexOpti id next to your record as a cache, but LexOpti stays the reference: a deleted client takes its reference with it, and resetting the sandbox clears every reference, so a link the lookup no longer finds is dropped, and the next link creates the client anew. LexOpti’s reference CRM links its contacts this way and finds them again after a restart.
Send an identity complete enough to screen: a person’s birth date and nationality, a French company’s SIREN and country. Without them, launching a check answers incomplete_identity with the fields to complete.
Each client your application creates through the API (POST /v1/clients) is screened at once and for free against the official asset-freeze and sanctions lists: the French national freeze register (DG Trésor), the EU financial sanctions list and the US OFAC SDN list. It is screened again, for free, when your application changes its identity (PATCH /v1/clients/{id}) and at each new publication of these lists. Any other client your token reaches is screened when your application asks for it: POST /v1/clients/{id}/preliminary-screening (202). Read the result on the client, or with GET /v1/clients/{id}/preliminary-screening; client.preliminary_screening_completedtells you when one changes. The members of the organization see no trace of it in LexOpti: the result reaches your application alone.
status is pending (usually answered within seconds), completed (read outcome: no_match or possible_match), failed or unavailable (never show either as a clean result). A match whose birth date contradicts the client is a probable namesake (homonym: true) and does not count in outcome. The fields are in the API reference; a sandbox answers its magic inputs at once.
The professional using your software stays responsible for the freeze obligation (art. L. 562-4 CMF). Your screens must not say more than the screening does:
No match: write « Aucune correspondance dans les listes consultées » (“No match in the lists searched”), with the lists, their publication dates (lists[].published_at) and the check date (checked_at). Never « client conforme », “compliant”, « pas de gel » or “not sanctioned”.
Possible match on a binding list (the French register, the EU list): tell the member to verify the identity. If it is the designated person, the assets are frozen without delay, nothing is made available to them (art. L. 562-5 CMF), and the freeze is reported to the DG Trésor.
OFAC match: “information on a US sanctions risk, to assess”, never a freeze in France; the EU blocking statute (Regulation (EC) No 2271/96) forbids applying some US measures.
Scope: freezes and sanctions only. The complete analysis (politically exposed persons, adverse media, registers, web analysis, classification) is a case: offer to create one.
Attribution: show each searched list’s attribution (current.lists[].attribution, the source and its publication date), as the reuse terms of the lists require.
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(newError('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 = newconsole.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(newError('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
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()).
Load the script as a module, place the components, and give them a session provider that asks your server for a one-time code (embedded components). Your server creates it with the member’s token, the exact origin of the page, and the PKCE challenge and the component the element handed to its session provider (one session per component):
Subscribe your endpoint once per connection and keep its secret, answered once, in your secret manager. Verify every delivery on its raw body with webhooks.verify, answer a 2xx quickly, and deduplicate on the event id: retries and replays keep it (receive webhooks).
Verifies a LexOpti webhook (Standard Webhooks) and returns its event:
pass the raw body, the request headers and the endpoint secret
(whsec_…). Throws when the signature or the timestamp is wrong. The
event's id is the webhook-id header: deduplicate on it.
The TRACFIN classification of a client, and of each case, is the member’s: they answer and validate it in LexOpti or in the embedded components, never your application. Read it to show where it stands: its state (to_complete, in_progress, validated, revalidate), its score and level, its last validation, its answers and the questions still unanswered (missing_answers), counted as the form counts them.
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(newError('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 = newconsole.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(newError('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
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()).
// What is left for the member to answer, in LexOpti.
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(newError('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 = newconsole.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(newError('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
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()).
GET /v1/cases/{id}/classification reads a case’s the same way, every axis but one: the suspicion axis is never returned by the API (excluded_axes: ["axe5"]). What the professional knows or suspects must not reach another system (art. L. 561-18 CMF), so neither its answers nor its effect on the score and the level leave LexOpti, by the API, the MCP server or the events; missing_answers does not count it either. The member still sees it in LexOpti and in the embedded components. Reading changes nothing, and a client never classified answers to_complete without answers. To hear of each validation, subscribe to classification.validated (events).
The member creates a client’s cases and classifies them in LexOpti. Read them to show them next to your record: GET /v1/cases?client_id= lists the cases of a client, main or not, newest first.
role: "demandeur"|"defendeur"|"appelant"|"intime"|"intervenant"|"partie_adverse"|"vendeur"|"acquereur"|"cedant"|"cessionnaire"|"contrepartie"|"bailleur"|"locataire"|...16 more ...|"autre";
role:"demandeur"|"defendeur"|"appelant"|"intime"|"intervenant"|"partie_adverse"|"vendeur"|"acquereur"|"cedant"|"cessionnaire"|"contrepartie"|"bailleur"|"locataire"| ... 16 more ... |"autre";
type:"person"|"company";
name:string;
monitoring_enabled:boolean;
}[];
...8 more ...;
updated_at:string;
}
dossierof
const page: {
data: {
id:string;
external_ref:string|null;
label:string|null;
type:string|null;
types:string[];
type_label:string|null;
status:"pending"|"running"|"completed"|"failed";
client_id:string|null;
client_ids:string[];
clients: {
id:string;
external_ref:string|null;
main:boolean;
}[];
parties: {
id:string;
entity_id:string;
external_ref:string|null;
role:"demandeur"|"defendeur"|"appelant"|"intime"|"intervenant"|"partie_adverse"|"vendeur"|"acquereur"|"cedant"|"cessionnaire"|"contrepartie"|"bailleur"|"locataire"| ... 16 more ... |"autre";
type:"person"|"company";
name:string;
monitoring_enabled:boolean;
}[];
...8 more ...;
updated_at:string;
}[];
has_more:boolean;
next_cursor:string|null;
}
page.
data: {
id: string;
external_ref: string |null;
label: string |null;
type: string |null;
types: string[];
type_label: string |null;
status: "pending"|"running"|"completed"|"failed";
client_id: string |null;
client_ids: string[];
clients: {
id: string;
external_ref: string |null;
main: boolean;
}[];
parties: {
id: string;
entity_id: string;
external_ref: string |null;
role: "demandeur"|"defendeur"|"appelant"|"intime"|"intervenant"|"partie_adverse"|"vendeur"|"acquereur"|"cedant"|"cessionnaire"|"contrepartie"|"bailleur"|"locataire"|...16 more ...|"autre";
type: "person"|"company";
name: string;
monitoring_enabled: boolean;
}[];
...8 more ...;
updated_at: string;
}[]
data) {
const
const parties:string[]
parties =
const dossier: {
id:string;
external_ref:string|null;
label:string|null;
type:string|null;
types:string[];
type_label:string|null;
status:"pending"|"running"|"completed"|"failed";
client_id:string|null;
client_ids:string[];
clients: {
id:string;
external_ref:string|null;
main:boolean;
}[];
parties: {
id:string;
entity_id:string;
external_ref:string|null;
role:"demandeur"|"defendeur"|"appelant"|"intime"|"intervenant"|"partie_adverse"|"vendeur"|"acquereur"|"cedant"|"cessionnaire"|"contrepartie"|"bailleur"|"locataire"| ... 16 more ... |"autre";
Calls a defined callback function on each element of an array, and returns an array that contains the results.
@param ― callbackfn A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the array.
@param ― thisArg An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
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(newError('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 = newconsole.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(newError('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
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()).
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(newError('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 = newconsole.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(newError('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
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()).
Each case carries its clients with your references (clients, the main one first), its other parties and their roles, its vigilance level, the risk level a member validated (risk_level, null until the first validation), where its classification stands (classification_state, the details with GET /v1/cases/{id}/classification) and its pending alerts (pending_alert_count). To hear of a new case and of each change of its risk level, subscribe to case.created and case.risk_level_changed (events).
Without embedded components, your server reads what the member needs next to your records and your screens show it, in your style. Read it on your server, with the member’s token, never from the browser, and never on each page you render: hundreds of records shown means hundreds of requests, repeated at every visit. The recommended pattern:
One batched request fills a cache on your side, at connection and when the member asks to refresh: GET /v1/clients with up to 100 of your records (ids, or your references in external_ref, comma-separated) and expand[] for what your screens show (read many records at once): the client’s vigilance_level and validated risk_level are always there, last_check, open_alerts_count, classification_state and cases when asked.
Webhooks keep it current: an event that names a client (client_id) or one of its cases (case_id), such as check.completed, alert.created, client.vigilance_level_changed, classification.validated or case.updated, makes your server read that one record again, then your open pages redraw it (events). Answer the delivery with a 2xx first, then read: the read never delays it. A case_id names your record through your reference of the case, which the event carries as case_external_ref when you set one, or through GET /v1/cases/{id}, whose external_ref and client_ids name your record and its clients. A record the read no longer returns (deleted, or unlinked from your application) leaves your cache.
Adds all the elements of an array into a string, separated by the specified separator string.
@param ― separator A string used to separate one element of the array from the next in the resulting string. If omitted, the array elements are separated with a comma.
join(","),
limit?: number |undefined
limit: 100,
});
const
const cache:Map<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;
};
...10more ...;
cases?: {
...;
} |undefined;
}>
cache = new
var Map:MapConstructor
new<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;
}>(iterable?:Iterable<...> | ... 1 more ... |undefined)=> Map<...> (+3 overloads)
Calls a defined callback function on each element of an array, and returns an array that contains the results.
@param ― callbackfn A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the array.
@param ― thisArg An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
map((
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) => [
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,
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]));
// On a webhook naming a client: that record alone, then redraw it.
asyncfunction
functionrefresh(clientId:string):Promise<void>
refresh(
clientId: string
clientId:string):
interface Promise<T>
Represents the completion of an asynchronous operation
LexOpti’s reference CRM works this way: at connection, its « Appels API » panel shows, for each page of 100 linked records, the clients with their expansions, their pending alerts (GET /v1/alerts?client_ids=…&status=pending, every page) and the cases linked to its records (GET /v1/cases?ids=…); then two requests for each webhook naming a linked contact, one more for the linked case; and none when a page is drawn.
An alert waits for a member’s review. Your screen may record it: the member chooses the decision and writes the note, your server sends it with PATCH /v1/alerts/{id}. The decision stays the member’s, the API never reviews on its own:
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(newError('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 = newconsole.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(newError('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
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()).
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(newError('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 = newconsole.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(newError('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
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()).
--json'{"status": "dismissed", "notes": "Homonym: different date of birth."}'
The report of a case is LexOpti’s own, in its version for partners: it never includes the suspicion axis (excluded_axes: ["axe5"]) and computes its scores without it. GET /v1/cases/{id}/report answers its metadata and a URL signed for 5 minutes, in the language of Accept-Language (the SDK’s locale). Download it from your server, check it against its sha256, then serve it to the member: the signed URL never reaches the browser, and the same version is the same file.
Creates and returns a Hash object that can be used to generate hash digests
using the given algorithm. Optional options argument controls stream
behavior. For XOF hash functions such as 'shake256', the outputLength option
can be used to specify the desired output length in bytes.
The algorithm is dependent on the available algorithms supported by the
version of OpenSSL on the platform. Examples are 'sha256', 'sha512', etc.
On recent releases of OpenSSL, openssl list -digest-algorithms will
display the available digest algorithms.
Example: generating the sha256 sum of a file
import {
createReadStream,
} from'node:fs';
import { argv } from'node:process';
const {
createHash,
} = await import('node:crypto');
const filename = argv[2];
const hash = createHash('sha256');
const input = createReadStream(filename);
input.on('readable', ()=> {
// Only one element is going to be produced by the
// hash stream.
const data = input.read();
if (data)
hash.update(data);
else {
console.log(`${hash.digest('hex')}${filename}`);
}
});
@since ― v0.1.92
@param ― options stream.transform options
createHash("sha256").
Hash.update(data: BinaryLike): Hash (+1 overload)
Updates the hash content with the given data, the encoding of which
is given in inputEncoding.
If encoding is not provided, and the data is a string, an
encoding of 'utf8' is enforced. If data is a Buffer, TypedArray, orDataView, then inputEncoding is ignored.
This can be called many times with new data as it is streamed.
@since ― v0.1.92
@param ― inputEncoding The encoding of the data string.
Calculates the digest of all of the data passed to be hashed (using the hash.update() method).
If encoding is provided a string will be returned; otherwise
a Buffer is returned.
The Hash object can not be used again after hash.digest() method has been
called. Multiple calls will cause an error to be thrown.
@since ― v0.1.92
@param ― encoding The encoding of the return value.
# DOWNLOAD_URL: the download_url it answers. No token: it is the
# credential, for 5 minutes.
curl-oreport.pdf"$DOWNLOAD_URL"
# The file LexOpti announced has its sha256.
sha256sumreport.pdf
What your screens cannot do by the API: answer or validate a classification, or see the suspicion axis (to create a case, see below). Send the member to LexOpti for those (deep links), or show them the embedded components. To refresh your screens without polling, follow the events: client.vigilance_level_changed, check.completed, alert.created, classification.validated, report.generated.
Log each call your server sends with its Request-Id header, to give to LexOpti’s support, and never log a token, the client secret, a code or a signed URL. LexOpti’s reference CRM shows this log in its « Appels API » panel.
Authorize your application on your sandbox and drive each path with its magic inputs: a last or company name containing SANCTION, EXPOSE or PRESSE gets a sanctions match, a politically exposed person or adverse media, and ERREUR makes the check fail (sandbox).
When a member unlinks LexOpti in your software, revoke their tokens at POST https://app.lexopti.com/api/auth/oauth2/revoke with HTTP Basic: first the refresh token (token_type_hint=refresh_token), which ends the grant, then the access token (token_type_hint=access_token). Drop the tokens even if a revocation fails. The code, in TypeScript, PHP and curl: revoke the tokens.
12. A whole organization: install once, every member signs in
An organization of 20 people uses your software. Rather than each member reading and accepting the same consent page, your application can be installed once for the whole organization, as an administrator does with Microsoft Entra’s admin consent or a Google Workspace trusted app. In LexOpti, the organization asks and LexOpti installs it: an organization’s settings only list the applications connected to it, read-only.
LexOpti installs it, at the organization’s request. The organization’s owner or admin asks LexOpti through the contact form (the “Connected applications” tab of its settings says so); LexOpti installs your application for the organization, with a recorded motive. The scopes your application is registered with are installed for every member. In your sandboxes too, LexOpti installs it on request.
Each member only signs in. Your authorization request is unchanged. A member who signs in to LexOpti gets no consent page for the installed scopes and comes straight back to your callback, with prompt=none too. Each member still gets their own tokens, in their name and with their role (a read-only member stays read only): LexOpti’s trail says which member did what, as anti-money-laundering rules require. Never share one member’s token with another. A person without a LexOpti account creates it from the sign-in page, or accepts their manager’s invitation, and then comes back to your callback the same way (a member without an account).
Map your users to members. Once your application is installed for the organization, GET /v1/members lists the organization’s members (id, name, email, role, nothing else, paginated like every list); before, or for an application a single member connected, it answers 403 installation_required. Match your users to them by email, and check with GET /v1/organization which member a token acts for (member.user_id).
Asking for more. A request with scopes beyond the installed ones shows the consent page again: the member consents themselves, or LexOpti installs it again, at the organization’s request, to extend it.
Withdrawal. When LexOpti withdraws the installation at the organization’s request (or revokes or blocks your application there), every member’s access ends at once: refreshing their tokens fails with invalid_grant, their access tokens get 401 invalid_token from LexOpti’s API, embedded components and MCP at the next request (they stay readable by the authorization server’s introspection and user information until they expire, 15 minutes at most), your embedded sessions close, and each of your webhook endpoints in the organization receives a last access.revoked and is disabled (webhooks). The next sign-in asks each member again.
An installation stays whoever leaves the organization, as with Microsoft Entra’s admin consent: it is the organization’s decision, which only a new request to LexOpti withdraws. If LexOpti disables your application, the installation stops acting and resumes when it is enabled again.
An application installed on the member’s computer and redirected to http://127.0.0.1 or a private-use scheme cannot be installed for an organization: nothing proves which program asks, so each member confirms every authorization. A sandbox-only application, or one whose production access is not approved yet, can be installed in its own sandboxes only.
Once the application is installed for the organization, the owner or an admin connected to your software can enrol the people of the organization who use your software and will work in LexOpti: POST /v1/members/enrolments, with their token, one person per call (email, first_name, last_name, rolemember or readonly, your external_ref). LexOpti creates the person’s account at once, decides their membership, and e-mails them (nothing to click). The answer carries connect_hint: put it in lexopti_hint on that person’s “Connect LexOpti” button.
Two modes, chosen by the organization; LexOpti switches between them at its request:
Nominative mode: the enrolled person clicks “Connect LexOpti”, their address is prefilled, they type the code they received, and that is all: their membership activates, no consent screen (the application is installed), they come back with their own token. member.joined tells you.
Delegated mode (the default of an installed application): the membership is active from the enrolment (status: activated, member_id). Your software keeps one connection, the owner’s or an admin’s, and names the acting member on each request with the header X-LexOpti-Acting-User: <member_id>. LexOpti runs the request as that member, with their role (a read-only member does not write), and every line of the trail says “identity asserted by <your application>”: your software says who acts, LexOpti did not verify it. POST /v1/embed-sessions with that header opens the embedded screens for the member, without signing in. Refusals: delegated_mode_required (the organization turned the mode off), owner_or_admin_required (the carrying connection is not an owner’s or admin’s), unknown_acting_user (not a person your application enrolled in this organization, or no longer a member).
A typed client of the LexOpti API. Every idempotent POST gets an
Idempotency-Key (kept across its retries); only requests safe to repeat
are retried after a failure, with jittered backoff or Retry-After. Errors are oRPC errors: problemOf(error) reads the
problem details.
// enrolment.status: "pending" (nominative) or "activated" (delegated, with member_id)
// enrolment.connect_hint → lexopti_hint of Camille's “Connect LexOpti” button
GET /v1/members/enrolments lists your enrolments and their state (pending, activated, expired after thirty days, cancelled); DELETE /v1/members/enrolments/{id} cancels one still waiting. The events member.enrolled and member.joined keep you informed. Refusals: owner_or_admin_required, installation_required, already_member, enrolment_pending, seat_limit_reached (402).
A record of your software (a matter, a mandate, an engagement…) becomes a LexOpti case (a dossier) with POST /v1/cases: its clients, existing clients of the organization (by their LexOpti id, or by your reference: link a contact first), the main one first; its natures, among those the organization’s profession offers; its other parties, people or companies with their role and your reference of each; your reference of the record. LexOpti creates it as its « Nouveau dossier » screen does, the member who authorized your application assigned to it, and charges it as the screen charges it: one credit per tranche of five people or companies, one at least, for twelve months of vigilance. Nothing is screened: launch the checks later (checks), or send launch_checks: true to launch the case’s analyses with its creation when that costs nothing more.
Show the cost first. POST /v1/cases/preview takes the same body, checks it as the creation does and writes nothing: credits.needed against credits.balance, and sufficient_credits. Create once the member confirmed, under a key of your record: a retry, or a second click, answers the same case. The creation checks the balance again: when the credits no longer cover it, it answers 403 quota_exceeded and creates nothing (subscription_inactive when the organization has no offer running). A reference already naming a case answers 409 external_ref_conflict: read that case with GET /v1/cases?external_ref=…. A nature or a role the profession does not offer answers validation_failed, each field named. In a sandbox the credits are computed as in production and never drawn (livemode: false).
The example creates the case of a matter: a property sale (vente_immobiliere, a nature lawyers and estate agents offer) with the selling company as a party (vendeur). Send the natures and roles of your organization’s profession instead: an accountant’s engagement may be tenue_comptable with no other party, a notary’s a custom nature with its label (case natures, party roles).
role: "demandeur"|"defendeur"|"appelant"|"intime"|"intervenant"|"partie_adverse"|...23 more ...|"autre";
type: "person"|"company";
name: string;
monitoring_enabled: boolean;
}[];
...8 more ...;
updated_at: string;
}, Error>;
...10 more ...;
listDocuments: Client<...>;
}
cases.
create: Client<Record<never, never>, {
clients: {
id?: string |undefined;
external_ref?: string |undefined;
}[];
types: string[];
type_label?: string |undefined;
label?: string |undefined;
parties?: ({
type: "person";
role: "demandeur"|"defendeur"|"appelant"|"intime"|"intervenant"|"partie_adverse"|"vendeur"|"acquereur"|"cedant"|"cessionnaire"|"contrepartie"|"bailleur"|"locataire"|"preteur"|"emprunteur"|"caution"|"tiers_payeur"|"donateur"|"donataire"|"heritier_legataire"|"mandant"|"mandataire"|"representant_legal"|"intermediaire"|"associe"|...4 more ...|"autre";
# What it costs: show credits.needed and credits.balance to the member.
curlhttps://app.lexopti.com/v1/cases/preview\
-H"Authorization: Bearer $LEXOPTI_ACCESS_TOKEN"\
--json"$BODY"
# Once the member confirmed: one case per matter, whatever the retries.
curlhttps://app.lexopti.com/v1/cases\
-H"Authorization: Bearer $LEXOPTI_ACCESS_TOKEN"\
-H"Idempotency-Key: crm-matter-$MATTER"\
--json"$BODY"
The answer is the case (201), with credits_charged and analyses_launched. Your endpoints receive case.created, then case.updated (changed_fields: parties) as its parties join, as when a member creates it in LexOpti. The member may also create the case themselves in your page, in LexOpti’s own form: <lexopti-new-case>.
When a customer of your software (a law firm, an estate agency, an accounting firm…) is not a LexOpti client yet, your server may prepare its organization for its manager to claim: the API calls this prepared organization a firm (/v1/firms). Nothing exists in LexOpti until they claim it: LexOpti e-mails them a claim link, which opens its normal sign-up with the organization’s details filled in. The manager checks them and their profession, accepts the terms, starts their trial or pays, and proves their e-mail with a code, as anyone signing up; LexOpti verifies the profession as for any organization. Only then does the firm become an organization, its manager its owner. Until then nothing can be written into it, nothing lists or counts it, and it blocks nothing.
Your application asks for its own token: client credentials with your client secret, resource the API, scope lexopti:firms. No member is behind it, and it serves /v1/firms only: a member’s token is refused there, and this one everywhere else. Only an application approved for production gets it (unauthorized_client otherwise), and a withdrawn approval stops it at its next call (production_access_required). It lives 15 minutes, without refresh token: ask for another.
Then POST /v1/firms: the organization’s name, its SIREN, its profession, its manager’s e-mail (and name, if you have it) and your reference of the customer, under a key of the customer: a retry answers the same firm, without its link. The answer is the firm, pending, with its claim_url, answered this once. The example prepares an estate agency; any supported profession works the same way. LexOpti e-mails the link to the manager, in the locale you give (fr by default). You may also show it to the manager signed in to your software; never send it yourself, nor to anyone else. Only an account with the invited e-mail may claim it (another address is refused), the link works once, for 7 days at most, and a developer account never claims one.
A typed client of the LexOpti API. Every idempotent POST gets an
Idempotency-Key (kept across its retries); only requests safe to repeat
are retried after a failure, with jittered backoff or Retry-After. Errors are oRPC errors: problemOf(error) reads the
problem details.
A SIREN already a LexOpti client answers 409 firm_exists: the organization already uses LexOpti, so ask its manager to invite your user (« Demandez à votre responsable de vous inviter ») and connect them as usual (step 2). Your application keeps one firm pending per SIREN (firm_pending) and per reference (external_ref_conflict), 50 at most at once (too_many_pending_firms). A pending firm blocks nothing: if the organization signs up on its own first, or another partner’s firm with the same SIREN is claimed first, yours is voided. Never claimed within 30 days, it expired: the manager’s e-mail is erased.
To bring the manager back connected to your software at the end of their sign-up, start your usual authorization (step 2) with one more parameter, lexopti_claim, the claim parameter of claim_url: LexOpti opens the organization’s sign-up directly, then the authorization resumes and your callback gets the code, for the new organization.
GET /v1/firms/{id} tells where the firm stands: pending, claimed (with organization_id, the id of GET /v1/organization once the manager authorized your application, and activated_at once its offer runs), expired or voided. No webhook tells it: a pending firm has no endpoint yet, so poll it, or wait for your callback. POST /v1/firms/{id}/claim-link issues a new link for a pending firm and e-mails it again, once a minute at most (rate_limited); the previous one stops working at once.
A typed client of the LexOpti API. Every idempotent POST gets an
Idempotency-Key (kept across its retries); only requests safe to repeat
are retried after a failure, with jittered backoff or Retry-After. Errors are oRPC errors: problemOf(error) reads the
problem details.