Skip to content

Concepts

This page explains the model behind the API: who your software acts for, what changes with the professional’s profession, how a client becomes screened, the difference between the two levels it reads, and why some decisions never go through the API. The fields and operations are in the API reference.

An organization is the structure of a regulated professional, such as a law firm, a notarial office, an accounting firm or an estate agency (GET /v1/organization): everything you read or write belongs to one. Your application never acts for the organization as a whole, but for one of its members, the people of the organization who use LexOpti: the one who chose the organization while authorizing your application. Each token is bound to that member and that organization and carries exactly the member’s rights: a member with a read-only role only reads, whatever the scopes, and a member who leaves the organization ends your access with them (authentication).

This is what lets the organization’s audit trail say who did what, and through which application. An integration used by several organizations holds one connection per member and organization.

LexOpti serves several regulated professions: lawyers, notaries, accountants, estate agents and other regulated professionals. The API is the same for all of them, with the same resources, fields and codes. What depends on the organization’s profession:

  • The words of LexOpti’s screens. The organization is a « Cabinet » for lawyers and accountants, an « Agence » for estate agents, an « Étude » for notaries and a « Structure » otherwise; a case is an « affaire » for lawyers and a « dossier » for the other professions. The API always says organization and case, and this portal organization, member and case: in your own screens, use your users’ words.
  • The case natures and the party roles a member may choose (party roles, case natures).
  • The risk questionnaire, its version named by policy (read a client’s classification).

A client is a business relationship with a person or a company. Creating a client only records an identity: nothing is screened and nothing is consumed.

Screening is a separate step, the check, for two reasons. It is billed, by dossier: a check is charged to the client’s dossier (a case; case_id, or its only open case, or else its business relationship dossier, opened for it), as LexOpti charges it. One credit opens a dossier of up to five people or companies for twelve months, each further five cost one more credit, and launching again within the dossier’s year and places is free. And it needs an identity complete enough to screen without confusing two people: a check on a person without birth date or nationality answers incomplete_identity.

A check screens the client and its related parties across every source: sanctions, politically exposed persons, asset freezes, registers, BODACC and adverse media. Sources answer at different speeds, so a check is asynchronous: running until every source answered, then completed, or failed when a source could not be screened. Your software learns the end through an event rather than by waiting.

Usage (GET /v1/usage) shows the organization’s credits and dossiers. A check its credits cannot pay is refused (quota_exceeded); without an offer running, credits are frozen and checks refused (subscription_inactive), while everything stays readable.

The vigilance level (vigilance_level: simplified, standard or enhanced) is derived by LexOpti from the screening results. The risk level (risk_level) is a judgment: the level a member validated in LexOpti after classifying the client.

The law puts that judgment on the professional, who stays responsible for their vigilance obligations (security and compliance). So the API reads a risk level but never sets one, and an acceptance decision never goes through it. When you show both levels, never present the vigilance level as the professional’s decision.

When a source changes about a client or party under ongoing vigilance, LexOpti raises an alert. It stays pending until a member reviews it: reviewed, dismissed or confirmed. Your software can record that review for the member, with the member’s rights.

A case is a matter or an engagement (a sale, a transfer of shares, a dispute, an accounting engagement…) involving one or more clients. Through the API, you create a case for existing clients, with its natures and its parties, as LexOpti’s « Nouveau dossier » screen does and charged as it charges it (POST /v1/cases, priced first by POST /v1/cases/preview: create a case from your record), and you link cases and their parties to your own ids (PUT /v1/cases/{id}/external-ref, PUT /v1/cases/{id}/parties/{party_id}/external-ref). The member works on them in LexOpti, or in your page through the embedded components (<lexopti-new-case>, <lexopti-case>, <lexopti-app>), which are LexOpti’s own screens: there the member creates a case, edits its title, its clients, its parties, its additional subjects and its assignees (the edit action), launches its analyses (launch-check), answers and validates its classification (tracfin2), reviews its screening results, generates its report and comments on it (comments), as far as the session keeps these parts and the member’s rights allow. A case is neither closed, reopened nor deleted from your page. A case has its own risk level (risk_level), the one a member validated with its classification, next to the vigilance level of its screenings.

Besides its clients, a case lists its other parties (the other side, a funder…), each with a role: a stable code in French, the profession’s own word. Each profession offers its own roles when a member adds a party; a role it no longer offers still shows on an older party, and new roles may be added: show an unknown one as autre.

role Meaning Offered to
vendeur, acquereur Seller, buyer lawyers, notaries, real estate, other professions
cedant, cessionnaire Transferor, transferee lawyers, notaries, accountants, real estate
bailleur, locataire Lessor, lessee lawyers, real estate
preteur Lender lawyers, notaries, accountants
emprunteur, caution Borrower, guarantor lawyers, notaries
tiers_payeur Third-party payer or funder every profession
contrepartie Counterparty accountants, other professions
donateur, donataire, heritier_legataire Donor, donee, heir or legatee notaries
intervenant Intervenor notaries
partie_adverse Opposing party lawyers
mandataire, representant_legal Proxy, legal representative every profession
intermediaire Intermediary or introducer real estate, other professions
associe Partner or shareholder lawyers, notaries, accountants
constituant, fiduciaire, beneficiaire Settlor, trustee, beneficiary lawyers
autre Other every profession
demandeur, defendeur, appelant, intime, mandant, tiers Plaintiff, defendant, appellant, respondent, principal, third party no longer offered, shown on older parties

A case has one or more natures (types in POST /v1/cases, type and types in the case), stable codes in French: those the organization’s profession offers in LexOpti’s « Nouveau dossier » screen, or custom with its free-form label (type_label, 2 to 160 characters), which every profession offers. A nature the profession does not offer answers validation_failed. GET /v1/organization tells which organization a token acts for; its profession is the one the organization chose in LexOpti.

Profession Natures offered (besides custom)
Lawyers real estate: vente_immobiliere, gestion_locative, copropriete, vente_judiciaire, fonds_commerce, droit_bail; companies: creation_societe, fusion_societe, cession_titres, gouvernance, societe_preponderance_immo, fonds_dotation; tax and finance: fiscalite, procedures_admin_fiscales_douanieres, mandat_representation_fiscale, prets_conventions_financieres, gestion_portefeuille, gestion_actifs, ouverture_comptes; criminal: procedure_penale, caution_penale; civil and commercial: responsabilite, recouvrement_creances, procedures_civiles, procedures_commerciales, contrats_commerciaux, ventes_mobilieres_corporelles; family and estates: successions, famille, protection_patrimoniale; employment: contrat_travail, contentieux_travail; sport: contrats_sportifs; intellectual property: propriete_intellectuelle; insurance: assurance_intermediation
Real estate sales: vente_immobiliere, vente_terrain, vente_neuf_vefa, vente_prestige, vente_viager, vente_demembrement, vente_judiciaire, echange_immeubles, mandat_recherche_achat; business premises: immobilier_entreprise_vente, location_professionnelle; lettings: location_habitation, location_prestige, location_saisonniere, mandat_recherche_location; business goodwill: fonds_commerce, location_gerance, droit_bail; company shares: cession_parts_societe; timeshare: temps_partage; management: gestion_locative, copropriete; on own account: marchand_biens_achat_revente, promotion_immobiliere
Accountants accounting: tenue_comptable, presentation_comptes, examen_limite, audit_contractuel, procedures_convenues, compilation_comptes, attestation_particuliere, examen_previsionnel, mission_legale_cse; tax: declarations_fiscales, declaration_ir_ifi, assistance_controle_fiscal, credit_impot_remboursement, conseil_fiscal; payroll: paie_social, conseil_social; legal: creation_societe_apports, operations_capital, cession_parts_actions, secretariat_juridique, montage_restructuration, dissolution_liquidation, consultation_juridique; finance: pilotage_gestion, business_plan_financement, audit_acquisition_evaluation, levee_fonds, subventions_aides_publiques; flows: mandat_paiement, recouvrement_creances, gestion_administrative; individuals: transmission_patrimoine
Notaries, other professions custom only

Some natures sit outside, or on the edge of, the anti-money-laundering perimeter (property management, rentals below the legal threshold): LexOpti offers them as its screen does and says so to the member.

LexOpti is the record the professional must keep (CMF L561-12). Your software keeps references to it: the link between your record and ours, and at most the levels you display. Webhooks carry ids only, and you read the details through the API when you need them: what you show stays current and within what the member may see.

Give a client or a case your own id, its external_ref (for example crm:contact:1042), and you need not store ours: pass it to POST /v1/clients, or set it later with PUT /v1/clients/{id}/external-ref (PUT /v1/cases/{id}/external-ref for a case), then find the record with GET /v1/clients?external_ref=crm:contact:1042 (or GET /v1/cases?external_ref=…).

  • It is an opaque string of 1 to 255 characters among A-Z a-z 0-9 : . _ -, unique per application, organization and kind: two organizations may use the same ids, and so may a client and a case. Keep it an opaque technical id, never personal data: no name, birth date or e-mail in it.
  • A record has at most one reference of your application: setting another one replaces it, and DELETE on the same path removes it. A reference already naming another record answers 409 external_ref_conflict; at creation, the client is then not created.
  • It belongs to your application: another application connected to the same organization never sees it (external_ref is null for it) and cannot find a record by it.
  • Events and webhooks name records by client_id and case_id, and add client_external_ref and case_external_ref when you set them.
  • A deleted record takes its reference with it, and resetting the sandbox clears every reference.
  • A party of a case who is not a client (the other side, a lender, a seller…) takes your id too: PUT /v1/cases/{id}/parties/{party_id}/external-ref. The reference names the person or company, not its place in one case: it shows on that party in every case it is part of (parties[].external_ref), and GET /v1/cases?party_external_ref=crm:contact:77 lists those cases. One reference names one party per application and organization.