Enrich

A row is either a registry_number (SIREN) with an optional ref, or a row of a resolve answer sent back exactly as you received it. A matched resolve row is enriched with its company; an ambiguous, not_found or invalid one comes back with its own status and a message, since there is no single company behind it. Any other column on a SIREN row, siren for instance, makes the row invalid.

fields chooses the columns for the whole batch. Name a field, or a theme to get all of its fields:

Without fields you get name, status, activity, workforce and head_office_address. The answer's top-level fields lists what every row carries. Codes come with their INSEE label, in French; activity also carries its scheme, and its label is null unless the scheme is naf2008. events is the latest event of each kind you list in event_kinds, newest first, each with occurred_on, source and bulk. When you leave event_kinds out it is every legal_entity.* kind of the timeline but filed accounts (legal_entity.accounts_filed and its corrections), which you get by naming them. Establishment event kinds are not available here. A bulk event is returned, with bulk: true. events is the raw log, as the timeline is: a correction or a cancellation is a kind of its own and is not applied, so a legal_entity.insolvency.opened can be there beside the legal_entity.insolvency.opened.cancelled that withdrew it, on a row whose collective_proceeding says open: false. Only the legal fields below apply corrections.

The legal fields are read from the notices of the BODACC, France's legal gazette, with the gazette's history included, bulk or not, and corrections applied: a cancellation withdraws the notice it names, a correction replaces it, and a court's retraction of an opening, which names no notice, withdraws the company's latest opening before it.

• collective_proceeding is an object on every row read in full. open says whether an insolvency proceeding is open; procedure is safeguard, accelerated_safeguard, reorganisation, liquidation or crisis_exit; stage is where the last judgment left it, opened, plan or closed. A company under an adopted plan has stage: plan and open: true, since the proceeding goes on under it. A liquidation closed and then resumed is the same proceeding opened again: stage: opened, with its first opened_on. opened_on is the date the proceeding opened, and can be null while open is true when the gazette gave no opening this API could read; updated_on and notice_url are the date and the notice of the last judgment. With no insolvency notice, open is false and the rest null.
• last_accounts_filed is the latest filing of accounts: published_on, the bulletin's date, and closing_on, the last day of the fiscal year filed. Not the figures. null when none is recorded.
• last_business_transfer is the latest sale of a business the company was party to: direction (sold or acquired), occurred_on, and counterparties, the other party's registry numbers. null when none is recorded.

Each carries source: "bodacc" and a notice_url, the notice to cite. A notice about a company that was partially disclosed in the registry, or that the registry did not hold yet, when the notice was read is recorded without its values, and stays so: the dates and open still count, but procedure, closing_on, counterparties or notice_url can be null on a row whose partially_disclosed is false. The BODACC covers companies in the trade register only. For an association or a sole trader outside it, open: false and a null means no notice was published, not that there was nothing to publish.

Each enriched row carries a sources object that names the source of each group of fields, null on a row that was not enriched:

{
  "sources": {
    "registry": "insee_sirene",
    "data_updated_at": "2026-09-14T08:30:00Z",
    "head_office_data_updated_at": "2026-09-01T12:00:00Z",
    "legal": { "registry": "bodacc", "published_on": "2026-06-02" }
  }
}

• registry is insee_sirene, the source of every value but events and the legal fields. data_updated_at is the registry's timestamp for the company's record, not an import time, and head_office_data_updated_at that of the head-office establishment's record, which the département and coordinates come from; it is null when no head-office field was selected.
• legal names the BODACC as the source of the legal fields: registry: "bodacc" and published_on, the bulletin date of the latest notice behind the legal fields you selected. published_on is null when no notice is behind them — or only notices recorded without their values, as above — and legal itself is null when you selected no legal field. On a row with partial: true, a null published_on can also mean the legal fields were not read in time: send the row again before you conclude there is no notice.
• Each event carries its own source and occurred_on, and each legal fact its source, dates and notice_url.

When you republish these values, give each group its source and date — Sirene with data_updated_at, the BODACC with published_on — rather than the time of your call.

A company whose registry record is partially disclosed comes back with partially_disclosed: true, and the masked values are null: its name and street address (postal_code and city survive), the head office's département and coordinates, and the rename and head-office-move events are left out of events. When only the head office is partially disclosed, its département and coordinates and those two events are withheld the same way, and the row also says partially_disclosed: true when the head office was read, that is when you selected a head-office field or events. The flag says whether something on this row is masked, so a null on a true row may be withheld by law rather than absent; the full card's partially_disclosed describes the company alone. The legal fields follow the company's status only: those of a partially disclosed company keep open, stage, direction and their dates, and lose procedure, closing_on, counterparties and notice_url, which are null, while a disclosed company whose head office is masked keeps them. A ceased company is enriched, with status: ceased. A valid SIREN the registry does not hold is not_found.

A batch spends at most 10 seconds reading. A row the budget did not reach comes back not_processed, with partial: true and a message; it is never reported as not_found. A row read only in part comes back enriched with partial: true, and the parts not read are null. Send either kind of row again. The batch is refused with 400 invalid_request only when it is not a batch (not JSON, no rows array, an empty one, more than 500 rows), when fields or event_kinds is empty or names something outside the lists above, or when event_kinds is sent without events in fields. A country other than fr is a 404. One batch runs at a time per organization, resolve and enrich together, and each server answers one at a time: a second one gets 429 concurrency_limited, even when batches are sent one after another. Retry after the Retry-After seconds the response gives, which differ between the two cases: do not hard-code them. For a file larger than one batch, submit a file job instead.

A batch is one call, however many rows it holds: on Free, one of the month's 1 000 lookups. Its rows are counted separately, on every plan, against the month's agent rows, shared with resolve: 1 000 on Free, 25 000 on Pro, 250 000 on Scale. Each row enriched or not_found is one row, and a SIREN repeated in a batch counts each time. invalid rows, resolve rows passed through (a resolve not_found included), and not_processed or partial rows are not counted. The rows your unfinished file jobs hold count as used. As on resolve, a batch admitted with rows left can take you past the allowance by up to its own size, and the next batch is refused with 402 quota_exceeded until the start of the next calendar month, UTC. Call it from a server with a secret key holding the read scope; a publishable fk_pub key is refused with 403 public_key_forbidden when it holds read, and with 403 insufficient_scope when it does not. Authentication covers both.