Neotimo

Neotimo API

Neotimo API > Émission et réception de factures électroniques pour PME françaises. L'environnement est porté par la clé, pas par l'URL (modèle Stripe) : un…

Government & public#government

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

Neotimo API

> Émission et réception de factures électroniques pour PME françaises. L'environnement est porté par la clé, pas par l'URL (modèle Stripe) : un seul hôte https://api.neotimo.com, ak_test_… = sandbox (simulateur, rien ne part vers le PPF), ak_live_… = production. Il n'existe pas de sandbox.neotimo.com — chez nous le sous-domaine désigne le tenant ({slug}.neotimo.com). GET /me vous dit dans quel mode votre clé se trouve.

Welcome! This API gives you programmatic access to the platform's resources:
organizations, accounts, files, settings, and more depending on which modules are enabled.

Whether you're a partner integrating our services, a dev automating workflows,
or an AI reading this doc at 3 AM — you're in the right place.


Quick Start — from zero to your first API call in 3 minutes

Step 1: Get your API key

Your administrator creates a key from the back-office (Settings > API Keys).

If you're an admin yourself, you can also create one via the API
(yes, it's recursive — and yes, we think that's elegant):

curl -X POST https://api.neotimo.com/api/v1/core/api-keys \
  -H "Authorization: Bearer  " \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My awesome integration",
    "roles": "user",
    "isTest": false
  }'

You'll get back:

{
  "data": {
    "id": 42,
    "name": "My awesome integration",
    "key": "ak_live_AbCdEfGhIjKlMnOpQrStUv",
    "keyPrefix": "ak_live_AbCd",
    "roles": "user"
  }
}

> Copy your key right now! It's only shown once.
> Like that brilliant idea you had at 3 AM but didn't write down.

Step 2: Make your first call

Add the X-Api-Key header to every request:

curl https://api.neotimo.com/api/v1/core/me \
  -H "X-Api-Key: ak_live_AbCdEfGhIjKlMnOpQrStUv"

That's it. No OAuth dance, no token refresh, no existential crisis.

Step 3: Verify it works

A successful /api/v1/core/me response looks like this:

{
  "data": {
    "name": "My awesome integration",
    "roles": ["user"],
    "tenantId": 1
  }
}
CodeWhat it means
200All good, you're in
401Invalid or missing key — double-check your header
403Key is valid but lacks the required role — ask your admin
429Too many requests — more on that below

Authentication

Two methods, pick your favorite — unlike restaurants, both are equally good here:

MethodHeaderBest for
API KeyX-Api-Key: ak_live_...Partners, webhooks, server-to-server integrations
Bearer TokenAuthorization: Bearer eyJ...Apps with user context

API keys are prefixed so you never mix them up:

  • ak_live_ — production (the real deal)
  • ak_test_ — sandbox (where you can break things without consequences)

API Key lifecycle

Every key has an expiration date (default 12 months, max 24). Forever-valid keys are a security smell — they outlive the engineer who created them and the integration they were meant for.

  • We email the key owner at T-30 / T-7 / T-1 days before expiry. No surprises.
  • Rotate before expiry with one atomic call:
  curl -X POST https://api.neotimo.com/api/v1/core/api-keys/42/rotate \
    -H "Authorization: Bearer  "

The response carries the freshly minted key (same shape as Create — copy it now, it's only shown once). The old key keeps authenticating during the overlap window (default 24h) so you can roll the secret across your deployment without downtime. A background job auto-revokes the old key once the window closes — no clean-up step on your side.

  • Need to revoke right now? Delete it from Settings > API Keys — effective immediately, all in-flight calls fail with 401.
  • A key is hashed at rest (with a server-side pepper). We can't recover it for you — only re-issue.

Response Format

Every response uses the same envelope. No surprises, we promise:

{
  "data": { ... },
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 142,
    "totalPages": 8
  }
}

Errors follow RFC 9457 — Problem Details.
Because even our errors are well-dressed.

HTTP 422 Unprocessable Entity
{
  "type": "https://docs.anplatform.fr/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "errors": {
    "email": ["The email field is required."]
  },
  "traceId": "00-abc123..."
}
StatusWhen
400Bad JSON / missing required param
401Not authenticated (no/invalid/expired key)
403Authenticated but no permission for this action
404Resource not found
409Conflict (duplicate, version mismatch, idempotency mismatch — see below)
422Validation error (business rules)
429Rate limit exceeded — see Rate Limits
500…

Endpoints 86

AFNOR XP Z12-013/FlowService

  • POST🇫🇷 Norme · Submit a new flow/flow-service/v1/flows?Name=string&FlowSyntax=CIISubmit a flow. A flow is a single-invoice file, with : an XML/PDF file with the data of the invoice The flow is created with a flowInfo object, allowing to…
  • POST🇫🇷 Norme · Select flows upon criteria/flow-service/v1/flows/searchRetrieves a set of flows matching the provided search criteria: Need at least one criterion to be specified Assuming a logical AND when combining criteria…
  • GET🇫🇷 Norme · Download the file of a flow/flow-service/v1/flows/:flowIdDownload a file related to a given flow: an invoice a life cycle an e-reporting
  • GET🇫🇷 Norme · Retrieve the list of webhooks created by the owner of the token/flow-service/v1/webhooks
  • POST🇫🇷 Norme · Subscribe to a webhook/flow-service/v1/webhooksThis operation creates and configures a new webhook, providing: The callback URL The metadata to filter on subsets of events The webhook belongs to the owner…
  • DELETE🇫🇷 Norme · Unsubscribe to a webhook/flow-service/v1/webhooks/:webhookUidDelete a subscription owned by the owner of the token The operation is allowed only buy the owner of the token
  • GET🇫🇷 Norme · Check whether the API service is up and running./flow-service/v1/healthcheck

AFNOR XP Z12-013/DirectoryService

  • POST🇫🇷 Norme · SIREN search (or legal unit)/directory-service/v1/siren/searchMulti-criteria company search.
  • GET🇫🇷 Norme · Consult a siren (legal unit) by SIREN number/directory-service/v1/siren/code-insee::sirenReturns the details of a company (legal unit) identified by the SIREN number passed as a parameter.
  • POST🇫🇷 Norme · Search for a SIRET (facility)/directory-service/v1/siret/searchMulti-criteria search for facilities.
  • GET🇫🇷 Norme · Gets a siret (facility) by SIRET number/directory-service/v1/siret/code-insee::siretReturns the details of a facility associated to a SIRET.
  • POST🇫🇷 Norme · Search for a routing code/directory-service/v1/routing-code/searchSearch for routing codes that meet all the criteria passed as parameters and return the routing codes in the desired format.
  • GET🇫🇷 Norme · Get a routing code by SIRET and routing identifier/directory-service/v1/routing-code/siret::siret/code::routing-identifierRetrieve the Routing Code data corresponding to the identifier passed in parameters.
  • POST🇫🇷 Norme · Search for a directory line/directory-service/v1/directory-line/searchSearch for directory lines that meet all the criteria passed as parameters and return the results in the desired format.
  • GET🇫🇷 Norme · Get a directory line./directory-service/v1/directory-line/code::addressing-identifierRetrieve the data from the directory line corresponding to the identifier passed in parameters.
  • GET🇫🇷 Norme · Liveness probe — returns 200 when the service is up. Requires the "health.read" scope since norm v1.3.0 (§4.4)./directory-service/v1/healthcheck

Neotimo/Annuaire

  • POSTStarts a PA registration./api/v1/neotimo/annuaire/registerThe caller hands us a matricule. If the entry is Unclaimed on our side, we mail a magic link to the DGFiP-known address and reply with a generic OK. Same…
  • GETLooks up a PA by matricule./api/v1/neotimo/annuaire/directory/pa/:matriculeOnly Status=Active entries surface. An unknown or non-Active matricule yields 404 with no extra information — we don't tell the caller whether the matricule…
  • GETSearches Active PAs by matricule, SIREN or denomination./api/v1/neotimo/annuaire/directory/pa/searchEvery filter is optional: matricule and siren match by prefix, denomination matches by substring (case-insensitive). page is 1-based; pageSize is clamped…
  • GETLists every Active PA, paged./api/v1/neotimo/annuaire/directory/paNo filter — useful to build your own peer index or cache. page is 1-based; pageSize is clamped server-side to 100.
  • GETReturns your directory entry./api/v1/neotimo/annuaire/meCapabilities are included. The fiche is resolved from your core:entityid claim — partners and other PAs never see this surface, only the logged-in owner does.
  • PUTUpdates contacts and capabilities of your entry./api/v1/neotimo/annuaire/meOne PUT, aggregate save. See An.Platform.Module.Neotimo.Presentation.Dtos.PaDirectory.PaDirectoryEditableDto for the diff semantics: null capabilities =…
  • POSTProbes one of your channels and records the outcome./api/v1/neotimo/annuaire/me/capabilities/:capabilityId/testWe hit the capability endpoint, capture whether it answers and how fast, then stamp the row with LastTestStatus / LastTestedAt. Marked…
  • GETResolves the responsible Plateforme Agréée for a SIRET or SIREN./api/v1/neotimo/annuaire/routing/:idReturns 200 when the identifier is currently routed in the mirror, 404 when it isn't (unknown SIRET/SIREN, or no active routing line today), 400 when the…

Core/Authz

  • GETReturns the in-memory authorization manifest as JSON./api/v1/core/authz/manifestFilter to a single module via ?module=Core (case-sensitive, matches the namespace-derived module name). Add ?includeDrift=true to receive the drift section…

Neotimo/Compliance

  • POSTDeclares a cash receipt for the specified F2 invoice (SC-07 scenario)./api/v1/neotimo/compliance/invoices/:frInvoiceId/cash-confirmationHuman action: the issuing client confirms the payment landed on its bank account. NEOTIMO emits the CDV 212 (Cashed) lifecycle event to the PPF over SFTP…
  • POSTCreates and qualifies a PPF-compliant F2 invoice (SC-01 scenario)./api/v1/neotimo/compliance/invoicesRuns the 3 lanes sequentially after validation: Lane A: recipient classification (F14 lookup → RecipientRoute) Lane B: F1 CII staging pre-generation…

Core/CustomFields

  • GETLists the custom field definitions applicable to an entity of a model./api/v1/core/custom-fields/:modelName/definitionsReturns the deduplicated, ordered union of the model-wide definitions and the owner-scoped definitions matching the entity's scope owners — the same…
  • GETReads the custom field values stored on an entity./api/v1/core/custom-fields/:modelName/:entityId/valuesReturns the stored rows only: a definition the entity never received a value for has no row here (merge with the applicable definitions client-side when…
  • PUTWrites custom field values on an entity./api/v1/core/custom-fields/:modelName/:entityId/valuesAll-or-nothing: every value is checked against the definition's rules — the SAME validations the UI enforces (required fields, conditional obligation, typed…

Core/DashboardMetrics

  • GETGET /api/v1/core/dashboard-metrics/{metricId}/api/v1/core/dashboard-metrics/:metricId

Core/Events

  • GETReturns the public event catalog as JSON./api/v1/core/events/catalogFilter to tenant-scoped-only or global-only events via ?tenantScoped=true / ?tenantScoped=false. Omitted, every event is returned. The payload uses…

Core/Me

  • GETReturns the caller's profile./api/v1/core/meReal callers: the Neotimo desktop agent on startup, partner integrations via API key checking which identity they hold, and CI scripts asserting the token…
  • DELETEDeletes the caller's account./api/v1/core/meSoft-deletes the account, kills every active session, signs the caller out. Refuses two cases: superadmin self-delete, and "sole admin of the tenant" — both…
  • GETExports the caller's personal data as a ZIP./api/v1/core/me/personal-dataGDPR Art. 15 right of access. See…
  • POSTRe-sends the email verification message./api/v1/core/me/email/send-verificationTargets the caller's primary address. Idempotent — silently no-ops when the address is already verified, so the UI can wire it to a "Resend" button without…
  • POSTSends an SMS OTP to the caller's phone./api/v1/core/me/phone/send-verificationGenerates a 6-digit OTP and texts it to the caller's phone. Requires a phone number on file — set one via the profile edit endpoint first.
  • POSTConfirms the caller's phone number./api/v1/core/me/phone/verifyValidates the OTP the user just typed and, on success, flips Account.PhoneNumberConfirmed = true. Codes expire after a few minutes — if the user took a coffee…
  • GETReturns the TOTP 2FA enrollment payload./api/v1/core/me/mfa/setupThe bits an authenticator app needs to enroll the caller: shared key plus an otpauth:// URI to feed a QR generator. When 2FA is already on, only the IsEnabled…
  • POSTEnables TOTP 2FA on the caller's account./api/v1/core/me/mfa/enableValidates the first TOTP from the authenticator app, turns 2FA on, and returns 10 single-use recovery codes. Show the codes to the user once — the platform…
  • POSTDisables TOTP 2FA on the caller's account./api/v1/core/me/mfa/disableDisables 2FA after one last TOTP check. The shared secret is wiped — re-enabling later starts from a fresh QR code and key. Recovery codes are also invalidated.
  • POSTRegenerates the caller's 2FA recovery codes./api/v1/core/me/mfa/recovery-codesMints a fresh batch of 10 recovery codes and invalidates the previous batch. Use when the user has burnt through their codes or lost them.

Neotimo/Directory

  • GETLooks up an entry by SIRET./api/v1/neotimo/directory/lookup
  • GETSearches the directory. The search term goes in `q` — not `query`, not `search`./api/v1/neotimo/directory/searchGET /api/v1/neotimo/directory/search?q=Avenir&type=PA&page=1&pageSize=20 q matches the entry name or SIRET, case-insensitively. Omitting it returns the whole…
  • GETReturns the caller's directory entry./api/v1/neotimo/directory/me
  • PUTUpdates the caller's directory entry./api/v1/neotimo/directory/me

Neotimo/Extraction

  • POSTQueues an extraction job for an uploaded file./api/v1/neotimo/extraction/jobs
  • GETReturns the current state of an extraction job./api/v1/neotimo/extraction/jobs/:id
  • POSTExtracts a file inline and returns the result synchronously./api/v1/neotimo/extraction/inline

Neotimo/Inbox

  • GETLists invoices received by the caller's tenant./api/v1/neotimo/inbox
  • GETReturns one received invoice in full./api/v1/neotimo/inbox/:id
  • GETDownloads the materialised file for the received invoice./api/v1/neotimo/inbox/:id/file
  • POSTMarks a received invoice as seen./api/v1/neotimo/inbox/:id/seen

Neotimo/Invoices

  • GETLists invoices owned by the caller's tenant./api/v1/neotimo/invoices
  • POSTCreates an invoice from a typed payload./api/v1/neotimo/invoicesSubmits the invoice straight away. Pass the Idempotency-Key header to make retries safe — the platform memoises the response for 24h. A SIRET in the sandbox…
  • POSTEmits an invoice from a PDF — the golden path./api/v1/neotimo/invoices/from-fileDrop the PDF, the platform extracts, normalises and emits in one round-trip. The response carries the job id (poll GET /extraction/jobs/{id}) and the emitted…
  • POSTPreviews routing and totals without persisting anything./api/v1/neotimo/invoices/preview
  • POSTRuns the shape and rules validator on a payload./api/v1/neotimo/invoices/validate
  • GETReturns one invoice by its public id./api/v1/neotimo/invoices/:id
  • POSTCancels an invoice that hasn't been cashed yet./api/v1/neotimo/invoices/:id/cancel
  • POSTEmits a full credit note for an existing invoice./api/v1/neotimo/invoices/:id/credit
  • GETDownloads the materialised invoice file in the requested format./api/v1/neotimo/invoices/:id/file
  • GETReturns the timeline of an invoice./api/v1/neotimo/invoices/:invoiceId/timeline
  • POSTPushes a lifecycle transition./api/v1/neotimo/invoices/:invoiceId/timelineThe transition must be in the catalog (see GET /timeline-transitions) and allowed from the invoice's current status — pushing cashed on a draft returns 422.…
  • POSTAttaches a file to a timeline event./api/v1/neotimo/invoices/:invoiceId/timeline/:eventId/attachments

Neotimo/Me

  • GETReturns the caller's profile./api/v1/neotimo/meResolves the tenant once via the standard pipeline (X-Tenant-Id header or the caller's account binding), then projects quota, mandate and a handful of…

Neotimo/Reporting

  • GETLists the caller's reporting periods./api/v1/neotimo/reporting/periods
  • GETReturns the summary of one period./api/v1/neotimo/reporting/periods/:id/summary
  • POSTCloses a reporting period./api/v1/neotimo/reporting/periods/:id/close
  • GETLists reporting transactions./api/v1/neotimo/reporting/transactions
  • POSTDeposits a batch of transactions into a period./api/v1/neotimo/reporting/transactions
  • GETReturns one reporting transaction./api/v1/neotimo/reporting/transactions/:id

Neotimo/Sandbox

  • POSTArms a sandbox scenario./api/v1/neotimo/sandbox/scenarios/:scenario/trigger

Neotimo/Tenants

  • GETLists the tenants the caller belongs to./api/v1/neotimo/tenants
  • POSTCreating a tenant from the API is not available./api/v1/neotimo/tenantsSandbox tenants are provisioned by Neotimo when your access is granted — one tenant per partner, which is what keeps your data out of everyone else's sandbox.…
  • GETReturns one tenant by id./api/v1/neotimo/tenants/:idThe caller can only fetch the tenant it is bound to. Reading another tenant returns 404 (indifferent on purpose — never reveals the existence of a tenant the…

Neotimo/TimelineTransitions

  • GETLists the transitions partners can push./api/v1/neotimo/timeline-transitions

Neotimo/Webhooks

  • GETLists the caller's subscriptions./api/v1/neotimo/webhooks/subscriptions
  • POSTCreates a webhook subscription./api/v1/neotimo/webhooks/subscriptionsReturns the cleartext signing secret one time — store it. Later GETs expose only the 6-char prefix. The URL must be HTTPS on the default port 443; raw IP…
  • DELETESoft-deletes a subscription./api/v1/neotimo/webhooks/subscriptions/:id
  • POSTFires a synthetic `neotimo.ping` delivery on a subscription./api/v1/neotimo/webhooks/subscriptions/:id/testUseful for onboarding — verifies your endpoint receives the signed POST, validates your signature check, and proves the SSRF guard accepts your host. The…
  • GETLists past webhook deliveries./api/v1/neotimo/webhooks/deliveries
  • POSTRe-enqueues one past delivery for a fresh attempt./api/v1/neotimo/webhooks/deliveries/:id/replayHangfire retries with its own exponential backoff (8 attempts max). Once retries are exhausted the row stays in failed. Replay it once you've fixed your…

Core/Referentials

  • GETGET /api/v1/core/referentials/vat-rates/api/v1/core/referentials/vat-rates

Sales/VatRates

  • GETGET /api/v1/sales/vat-rates/api/v1/sales/vat-rates

Core/WorkflowActions

  • GETReturns the workflow actions catalog as JSON./api/v1/core/workflow-actions/catalogThe payload uses System.Text.Json with camelCase property names — see An.Platform.Module.Core.Presentation.Api.WorkflowActionCatalogApiResponse for the…

API details

Base URL
https://api.neotimo.com
Authentication
A bearer token in the Authorization header
An API key in the X-Api-Key header
Operations
86 operations on 76 pathsGET 45POST 35PUT 3DELETE 3
Main resources
Neotimo/Invoices 12Core/Me 10AFNOR XP Z12-013/DirectoryService 9Neotimo/Annuaire 8AFNOR XP Z12-013/FlowService 7Neotimo/Reporting 6Neotimo/Webhooks 6Neotimo/Directory 4Neotimo/Inbox 4Core/CustomFields 3
Response formats
application/json text/json text/plain
Description format
OpenAPI 3.0.1, API version v1

How to test the Neotimo API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Neotimo API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “🇫🇷 Norme · Submit a new flow” (POST /flow-service/v1/flows?Name=string&FlowSyntax=CII), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Neotimo API?

Neotimo API > Émission et réception de factures électroniques pour PME françaises. L'environnement est porté par la clé, pas par l'URL (modèle Stripe) : un… It is listed under Government & public and has 86 endpoints.

Who publishes the Neotimo API?

It is listed from Neotimo's public API description (an OpenAPI document), not published by Neotimo on Swastik Codes. Anyone who controls neotimo.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Neotimo API?

Requests go to https://api.neotimo.com. Endpoint paths are added to this base URL.

How do I authenticate with the Neotimo API?

It accepts 2 methods: A bearer token in the Authorization header; an API key in the X-Api-Key header.

How many endpoints does the Neotimo API have?

86 operations on 76 paths (45 GET, 35 POST, 3 PUT, 3 DELETE). The largest groups are Neotimo/Invoices, Core/Me, AFNOR XP Z12-013/DirectoryService, Neotimo/Annuaire.

Is forking the Neotimo API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.