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.
One member, one organization
Section titled “One member, one organization”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.
Every profession, one API
Section titled “Every profession, one API”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
organizationandcase, 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).
Clients and checks
Section titled “Clients and checks”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.
Two levels: vigilance and risk
Section titled “Two levels: vigilance and risk”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.
Alerts and cases
Section titled “Alerts and cases”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.
Party roles
Section titled “Party roles”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 |
Case natures
Section titled “Case natures”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.
References, not copies
Section titled “References, not copies”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.
Your own ids
Section titled “Your own ids”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
DELETEon the same path removes it. A reference already naming another record answers 409external_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_refisnullfor it) and cannot find a record by it. - Events and webhooks name records by
client_idandcase_id, and addclient_external_refandcase_external_refwhen 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), andGET /v1/cases?party_external_ref=crm:contact:77lists those cases. One reference names one party per application and organization.