Iwana
← Developers

REST API v1

Connect your CRM or ERP to Iwana in a few hours. An API key for one workspace, OAuth 2.0 for a user who authorises you, the whole API from the first key, and signed webhooks.

REST JSON API keys OAuth 2.0 HMAC webhooks Full access

Quick start

Three steps to your first successful request. Everything is configured from the pro dashboard.

  1. Create an API keySettings → Developers → New key. Copy the secret straight away — it is shown once. Shipping a product that several businesses will install? Use OAuth, below.
  2. Test authenticationCall GET /integrations/me to check the organisation and the active permissions.
  3. Sync your dataRead the catalogue and the team, create or update clients and appointments, then subscribe a webhook for real-time updates.

curl example — replace the key with yours:

curl -s https://iwana.fr/v3/api/v1/pro/integrations/me \
  -H "Authorization: Bearer iw_live_xxxxxxxx_your_secret_here"

Authentication

Two ways to reach a workspace, both landing on the same API, the same /pro/* routes and the same permission checks. An API key names the workspace; an OAuth token names the user, the workspace and your application. Neither manages credentials (API keys, webhooks, plugins) nor invokes the AI: those stay in the app.

API keyOAuth token
Who issues itA workspace OWNER/ADMIN, in Settings → DevelopersThe user, on the consent page, for one PRO workspace
What it namesThe workspaceThe user and the workspace and the app
PermissionsThe whole API described hereThe whole API, within the user’s role, re-checked on every request
LifetimeUntil revokedAccess 1 h · refresh 3 years · until revoked
Revoked byWorkspace admin · Iwana staffWorkspace admin (“Connected apps”) · Iwana staff (deactivating the app)
HeaderAuthorization: Bearer iw_live_…Authorization: Bearer iwa_at_…
Authorization: Bearer iw_live_<prefix>_<secret>

Production keys

Prefix iw_live_* — access to the organisation’s real data.

Test keys

Prefix iw_test_* — reads the workspace’s real data and refuses every write (403 test_key_read_only): enough to build an integration end to end without touching the diary. It is not a separate demo workspace, and none exists. The refusal comes before the body is read — on every POST, PUT, PATCH and DELETE, read-only previews included — so body validation (400 validation_failed) can only be exercised with a live key.

The organisation is embedded in the key or the token: you do not need to send x-workspace-id or any other context header.

OAuth 2.0 — Sign in with IWANA

Authorization Code with a client secret. PKCE (S256) is honoured when the client sends it and not required. Tokens are opaque: no OpenID Connect, no JWKS, no id_token — identity comes from GET /oauth/userinfo. The token opens the whole API described here, within the user’s role: a VIEWER’s token cannot write.

EndpointMethodAuth
https://iwana.fr/v3/oauth/authorizebrowserthe user’s Iwana session
https://iwana.fr/v3/api/v1/oauth/tokenPOST, form-encodedclient_id + client_secret (body or HTTP Basic)
https://iwana.fr/v3/api/v1/oauth/userinfoGETBearer iwa_at_…

1. Register your app

Iwana staff create the app: name, logo, up to five redirect_uris matched exactly (http or https, no fragment). You receive a client_id (iwa_…) and a client_secret (iwa_cs_…) — the secret is shown once and stored hashed. Every app is confidential: the secret is required at the token endpoint, PKCE adds to it but does not replace it.

Write to [email protected] with the app name, a logo and your callback URLs.

2. Send the user to Iwana

GET https://iwana.fr/v3/oauth/authorize
    ?client_id=iwa_…
    &redirect_uri=https://crm.example/auth/iwana/callback
    &response_type=code
    &state=<random>
    &code_challenge=<S256>&code_challenge_method=S256

No scope parameter: the token covers the whole API. An unknown client_id or a redirect_uri that is not registered shows a dead-end page and never redirects. A user without a PRO workspace sees “reserved for professionals”; with several workspaces, they pick which one to authorise. A remembered consent skips the card.

The browser comes back to redirect_uri?code=iwa_ac_…&state=…, or ?error=access_denied&state=… if the user refused. The code lives 60 seconds and works once.

3. Exchange the code

POST https://iwana.fr/v3/api/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=iwa_ac_…&redirect_uri=<same as step 2>
&client_id=iwa_…&client_secret=iwa_cs_…&code_verifier=…
{
  "access_token": "iwa_at_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "iwa_rt_…",
  "scope": "…"
}

Send code_verifier only if you sent a code_challenge in step 2. The client may authenticate in the body or with HTTP Basic.

4. Call the API

GET https://iwana.fr/v3/api/v1/pro/clients
Authorization: Bearer iwa_at_…

No x-workspace-id header: the token carries the workspace. Writes made this way are attributed to your app in the audit log, and an appointment created this way carries source: API.

5. Refresh

grant_type=refresh_token&refresh_token=iwa_rt_…&client_id=iwa_…&client_secret=iwa_cs_…

Returns a new access_token; the refresh_token stays the same. After three years, or once the grant is revoked, the answer is invalid_grant and the user must sign in again. Refresh at the hour mark rather than per request: the token endpoint has its own, much smaller limit.

Who is signed in

GET https://iwana.fr/v3/api/v1/oauth/userinfo
Authorization: Bearer iwa_at_…

{
  "sub": "<user id>", "email": "…", "email_verified": true, "name": "…", "picture": null,
  "org_id": "<workspace id>", "org_name": "Plomberie Dupont", "role": "OWNER",
  "scope": "…"
}

sub + org_id is the pair to link to your own user record.

OAuth errors

The token endpoint speaks RFC 6749: { "error": "invalid_grant", "error_description": "…" } with invalid_request, invalid_client (401, with WWW-Authenticate), invalid_grant, unsupported_grant_type. A rejected bearer on any PRO route is a 401 with the usual { "error": { "code": "invalid_token" } } envelope.

Lifetimes

WhatLivesThen
Authorization code60 s, one useinvalid_grant
Access token1 hourrefresh
Refresh token3 years, flatthe user signs in again
Grantuntil revokedevery token dead at once
API keyuntil revoked401

Revocation

There is no revocation endpoint: the workspace admin cuts your app off from Settings → Developers → Connected apps, and Iwana staff can deactivate the app everywhere. Either way every token is refused from the next request on, including a freshly refreshed access token. A member who is removed or suspended loses their tokens the same way.

With a generic library

Any standard OAuth 2.0 client works. Two configurations ready to paste:

Passport (passport-oauth2)

new OAuth2Strategy({
  authorizationURL: 'https://iwana.fr/v3/oauth/authorize',
  tokenURL: 'https://iwana.fr/v3/api/v1/oauth/token',
  clientID, clientSecret, callbackURL,
  pkce: true, state: true,
}, async (accessToken, refreshToken, _profile, done) => {
  const me = await fetch('https://iwana.fr/v3/api/v1/oauth/userinfo', {
    headers: { authorization: `Bearer ${accessToken}` },
  }).then((r) => r.json());
  done(null, { id: me.sub, orgId: me.org_id, accessToken, refreshToken });
});

NextAuth / Auth.js

{
  id: 'iwana', name: 'IWANA', type: 'oauth',
  authorization: 'https://iwana.fr/v3/oauth/authorize',
  token: 'https://iwana.fr/v3/api/v1/oauth/token',
  userinfo: 'https://iwana.fr/v3/api/v1/oauth/userinfo',
  clientId, clientSecret, checks: ['pkce', 'state'],
  profile: (p) => ({ id: p.sub, email: p.email, name: p.name, image: p.picture }),
}

Base URL

Every endpoint lives under the PRO prefix:

https://iwana.fr/v3/api/v1/pro

The examples below omit this prefix for readability. Identifiers (`id`, `clientId`, `orgId`…) are opaque, unprefixed strings: store them as they are, do not parse them.

Check your key

GET/integrations/me

Returns orgId, actor, permissions, locale and timezone. Ideal as an integration health check.

{
  "orgId": "<workspace id>",
  "actor": { "kind": "api_key", "id": "<key id>" },
  "permissions": ["appointment:read", "appointment:write", …],
  "locale": "fr",
  "timezone": "Europe/Paris"
}

Common rules

What holds for every route, and what the OpenAPI specification spells out operation by operation.

Unknown fields: refused on the way in, ignored on the way out

A request body (or a query string with declared parameters) carrying a field that is not declared is refused with 400 validation_failed — it is not silently dropped; so is a number that is not one (limit=abc). The other way round, a response may gain fields without notice: ignore the ones you do not know.

Success codes and delete answers

A create answers 201. Reads, updates, deletes and the POSTs that only compute — /clients/import/check, /companies/lists/preview, /communications/preview, /workflows/{id}/test, /map/route — answer 200. A delete is never a 204: it answers a small JSON body, { "ok": true } on most routes and { "id": "…", "deleted": true } on /companies and /companies/lists; each operation’s response in the specification says which.

Retries: Idempotency-Key

On creates — POST /appointments, /clients, /contacts, /companies, /sites, /equipments, /quotes, /invoices (and from-quote, from-intervention, from-contract), /invoices/{id}/payments, /invoices/{id}/credit-note, /quotes/dpgf, quote and project duplication, /interventions, /projects, /tasks, /contracts — send Idempotency-Key: <8 to 128 characters>. The same key on the same route within 48 h returns the first response instead of creating a duplicate. An error is not stored: retry it with the same key. Other routes ignore the header.

Your ids and duplicates

POST /clients creates a record on every call without id: it never matches an existing record by email or phone. Deduplication is yours: record the mapping with PUT /external-refs and look it up with GET /external-refs before creating (answer { "item": null } when nothing matches).

Updates

Three forms, stated on each operation: a POST that creates or updates depending on id; a field-by-field PATCH { "field": "…", "value": … } (quotes, invoices, contracts, equipment, interventions, projects); a classic partial PATCH (sites). Amounts named …Cents are cents; a service’s price is euros.

Source and AI

An appointment written with a key or a token carries source: API, unless the body sends its own source. A key never calls the AI: workflow generation and PDF extraction answer 403 scope_required and are not in the specification. An automation saved with a key cannot add or change a Léo step, a template included: 403 scope_required, details.reason: ai_step_session_only. Léo steps a person wrote stay as they are.

ERP modules

Equipment, contracts, quotes, invoices, interventions and the price library need the ERP modules in the workspace’s plan; otherwise the answer is 402 erp_required. When the ERP offer is switched off for the whole platform the answer is 403 offer_disabled (with details.offer = "erp"), whatever the subscription.

Lists and paging

ListPage size (default / max)Shape
/appointments, /sites200 / 500{ items, total, limit, offset }
/clients, /contacts50 / 100{ items, total, limit, offset }
/companies50 / 200{ items, total }
/equipments, /interventions, /projects200 / 500{ items, total }
/contracts300 / 500{ items, total }
/quotes, /invoices500 / 500{ items, total }
/tasks500, no paging{ items, total, cap }
/activity-log, documentslimit + before cursor{ items, nextBefore }
Catalogue, team, settingsthe whole listarray or { items }

A /clients list without kind returns individuals only: send kind=ALL to include companies. Each operation’s response schema says which of these shapes it returns.

Team

Workspace members and teams: a member's membership id is what an appointment's memberIds expects. A key can also invite people and organise teams.

GET/team

Members (membership id = an appointment’s memberIds), teams and who is in which.

POST/team/members/invite

Invites a colleague into the workspace (not a client): an invitation email valid 14 days. OWNER role refused.

POST/team/teams

Creates or renames a team; POST /team/teams/{id}/members to add a member.

Appointments

Appointments (type=APPOINTMENT) and blocked slots (type=UNAVAILABILITY, including those imported from Google or Outlook) go through the same routes; lists return appointments unless you ask for type=UNAVAILABILITY. The source is marked API when called with a key or a token, unless the body sends its own.

GET/appointments

Paginated list (limit 200 by default, 500 at most). Filters: from, to (ISO date), status or statuses (comma-separated: PENDING, CONFIRMED, EXPIRED…), clientId, siteId, companyId, projectId, memberIds, serviceIds, search.

GET/appointments/{id}

One appointment with its client, service, site, assigned crew and intervention report.

GET/appointments/{id}/history

The appointment’s log: edits, status changes, messages sent.

GET/appointments/counts

Counts per tab: upcoming, today, requests, cancelled, history.

POST/appointments

Creates an appointment, or updates it when the body carries its id (an unknown id answers 404, never a create). serviceId is required to create, clientId optional; startAt / endAt in ISO 8601 UTC, required on an update too. An omitted field keeps its value, null clears it. Send an Idempotency-Key header so a retry never creates a duplicate.

PATCH/appointments/{id}/status

Changes the status (e.g. CONFIRMED, COMPLETED, CANCELLED) without rewriting the whole object. Emits appointment.updated, or appointment.cancelled for CANCELLED.

DELETE/appointments/{id}

Cancels and removes the appointment: afterwards GET answers 404 and lists no longer return it. To keep a cancelled appointment visible, set its status to CANCELLED instead.

GET/calendar/events

A diary window: appointments, blocked slots, closed days (from / to).

GET/availability/resolve

Effective working windows per member and day (from / to). A range over 62 days (inclusive) is refused with 400 range_too_long: split longer periods into several calls.

POST/availability/schedules

Creates or updates a member’s planning; an overlap answers 409 schedule_conflict.

GET/availability

Closure days and observed bank holidays.

Creation body

{
  "serviceId": "<service id>",
  "clientId": "<client id>",
  "startAt": "2026-08-10T09:00:00.000Z",
  "endAt": "2026-08-10T10:00:00.000Z",
  "memberIds": ["<member id>"],
  "customFields": { "crmDealId": "42" },
  "internalNotes": "Synced from CRM"
}

Clients

The address book. /clients holds individuals (kind=INDIVIDUAL) and companies (kind=COMPANY); /companies is its company view, /contacts the people attached to an account. A client is not a team member: for a colleague, see POST /team/members/invite.

GET/clients

Paginated list (50 by default, 100 at most) with search over name, email and phone. Without kind, individuals only: kind=ALL for everything, kind=COMPANY for companies. view=list for a lighter answer.

GET/clients/{id}

Full record: contact details, tags, custom fields, number of contacts and sites.

POST/clients

Creates a record, or updates it when the body carries its id. Without id it always creates: no matching on email or phone. Deduplicate with /external-refs. A company SIRET already used answers 409 siret_already_used (details.clientId names the record). Idempotency-Key accepted.

DELETE/clients/{id}

Deletes the record (soft delete: it leaves lists and GET answers 404).

GET/clients/{id}/duplicates

Possible duplicates: same SIRET or same name. Read-only.

POST/clients/{id}/merge

Merges this duplicate into targetId: appointments, sites, quotes… move to the target, the source record goes to the bin.

POST/clients/{id}/convert

Individual ↔ company, keeping the id and everything attached to it.

POST/clients/import

Bulk import (20,000 rows at most); with target, matching on email, phone, SIRET or name and a skip / update / create choice.

POST/clients/{id}/portal-link

Link to the customer portal, created once then reused. Sends nothing.

POST/clients/{id}/documents

Uploads a document (base64 data URL, 14 MB at most); GET for the list.

POST/contacts

Creates or updates a person attached to an account (clientId required to create).

POST/companies

Creates or updates a company (name required); a SIRET already used answers 409 siret_already_used, as on /clients. GET /companies for the list (50 by default, 200 at most).

GET/companies/lists

Imported or hosted company and contact lists.

Creation example

{
  "firstName": "Marie",
  "lastName": "Dupont",
  "email": "[email protected]",
  "phone": "+33612345678",
  "customFields": { "hubspotId": "12345" }
}

Sites, equipment & contracts

A site is an address where the work happens: a contact usually has several, and it is the site — not the contact — that carries the gate code, GPS coordinates and the people to reach on the spot. A piece of equipment is what is installed there, a maintenance contract what covers it.

GET/sites

The workspace’s addresses (200 by default, 500 at most). Filter with ?clientId=, ?clientIds= or ?companyId=.

GET/sites/{id}

One site with its contacts (owner, agency, tenant…).

POST/sites

Creates a site (create only). An owner is required: clientId or companyId — without one, 400 owner_required; line1 is optional; lat/lng if you already have them.

PATCH/sites/{id}

Updates a site: an omitted field keeps its value, null clears it.

POST/sites/{id}/contacts

Replaces the list of people at the site.

GET/equipments

Installed equipment. Filter with ?siteId=, ?clientId= or ?companyId=.

POST/equipments

Creates an equipment item: label and clientId required, siteId must belong to the same client.

PATCH/equipments/{id}

Updates one field: { field, value }; an unknown name goes to customFields.

GET/contracts

Maintenance contracts (300 by default, 500 at most).

POST/contracts

Creates a contract: clientId and startsOn required; lines and covered equipment afterwards.

POST/contracts/{id}/equipment/sync

Replaces the whole set of covered equipment and their cadence.

A site belongs to a contact or a company, and a piece of equipment to a client and optionally to one of its sites: create the contact before the site, and filter equipment with ?siteId= to find what is installed at one address. Equipment and contracts need the ERP modules.

Projects (chantiers) & tasks

A chantier groups phases, work items, rooms, reserves, measurements, documents, parties and partner companies. The tasks of /tasks are the workspace’s to-do list, separate from a chantier’s work items.

GET/projects

Chantiers (200 by default, 500 at most); counts=1 for counts per status.

POST/projects

Creates a draft chantier (reference CH-…). Idempotency-Key accepted.

PATCH/projects/{id}

Updates one field: { field, value }.

GET/projects/{id}/structure

Everything inside: phases, work items, reserves, money, quotes, invoices, appointments, documents.

POST/projects/{id}/phases

Adds or updates a planning phase; the same pattern for /tasks, /rooms, /reserves, /measurements.

POST/projects/{id}/participants

Invites a company or a person onto the chantier: the invitation goes out by email and SMS.

GET/tasks

The workspace’s tasks by due date (500 at most, no paging).

POST/tasks

Creates or updates a task (title required). On an update, send the whole task.

About forty operations in all on chantiers: the OpenAPI specification lists every one, under the “Chantiers” tag.

Configuration, catalogue, workflows & communications

The catalogue (services, locations, categories, specialties — read it to map your IDs before creating appointments; a key can also change it), business rules, custom fields, automations and the messages sent to clients.

GET/catalog/services

Services on offer with variants, category and locations: duration (durationMinutes), price in euros. The whole list, no paging.

POST/catalog/services

Creates or updates a service (name and durationMinutes required). On an update, send the whole service.

GET/catalog/locations

Places of business (addresses, zones, online).

GET/catalog/categories

Service categories.

GET/catalog/specialties

Who can perform each service: members, teams, crew size.

GET/business-rules

Business rule definitions and values (lead times, cancellation…); POST to change one.

GET/fields

Custom fields of one record type (?scope=client, appointment…). Values live in customFields, under the field’s key.

GET/workflows/bootstrap

The list of automations and published templates.

POST/workflows

Creates a draft automation (from a template, a spec or blank); PATCH …/status to activate it.

POST/workflows/{id}/test

A dry run on a real record: shows what each step would do, sends nothing.

POST/workflows/runs/{runId}/approve

Approves a waiting run: the rest, sends included, runs.

GET/communications/history/{id}

One sent message in full, with its delivery dates.

PATCH/communications/notifications/{id}

Switches a client notification on or off.

Drafting workflows with AI is not open to keys. Test sends from /communications/notifications/…/test really go out (an SMS is billed): send to, a key has no account address.

Statistics, activity log & geo

Dashboard indicators, the workspace’s activity log and address tools.

GET/dashboard/stats

KPIs, series and breakdowns over a period (range=7d, 30d, 90d, ytd, mtd or custom).

GET/dashboard/home

Home tiles: open quotes, unpaid invoices, revenue this month.

GET/activity-log

Activity feed, newest first: limit (50 by default, 200 at most), before cursor, kinds filter.

GET/geo/suggest

Address autocomplete (6 suggestions); /geo/resolve to geocode.

The figures are the dashboard’s, recomputed on every call: cache them rather than re-reading them in a loop.

External ID mapping

Iwana does not deduplicate for you: POST /clients without id always creates. For an idempotent sync, store the correspondence between your IDs and Iwana’s, and look it up before creating.

GET/external-refs?provider=&entityType=&externalId=

Resolves your ID to the Iwana ID (or back with localId). Without a match the answer is 200 { "item": null }, not a 404.

PUT/external-refs

Creates or updates the mapping (provider, entityType, localId, externalId); each side is unique per provider and entityType.

PUT /external-refs
{
  "provider": "hubspot",
  "entityType": "client",
  "localId": "<client id>",
  "externalId": "12345"
}

provider and entityType are free text (hubspot, client…): pick values and keep them.

Outgoing webhooks

Subscribe an HTTPS URL from Settings → Developers. Iwana sends a JSON POST on every event, signed so you can verify authenticity. The body is always { event, orgId, data, occurredAt }. data stays short: the record’s id, related ids, the status, ISO dates and amounts in cents — no names, notes or addresses, except a contact’s email and name in client.created / client.updated. Re-read the record with GET when you need all of it.

Available events

appointment.createdappointment.updatedappointment.cancelledclient.createdclient.updatedclient.deletedquote.createdquote.updatedquote.deletedinvoice.createdinvoice.updatedinvoice.deletedpayment.createdintervention.createdintervention.updatedintervention.deletedproject.createdproject.updatedproject.deleted

Delivery headers

Iwana-Signature: sha256=<hex hmac-sha256 of the raw body>
Iwana-Event: appointment.created
Iwana-Delivery: <uuid, unique per attempt>

Event body

{
  "event": "appointment.created",
  "orgId": "<workspace id>",
  "data": {
    "id": "<appointment id>",
    "startAt": "2026-08-10T09:00:00.000Z",
    "status": "PENDING"
  },
  "occurredAt": "2026-08-07T12:00:00.000Z"
}

HMAC verification — compute the SHA-256 HMAC of the raw body (JSON as sent) with the secret shown once when the subscription was created. Compare with Iwana-Signature. Answer 2xx within 15 seconds. Each event is delivered once — there is no automatic retry today. Failures are visible in Settings → Developers; to catch up on a missed event, periodically re-read the lists (GET /appointments?from=&to=, GET /clients, GET /invoices…).

Errors

Every error has the same shape and carries the identifier of the request that produced it. Quote requestId when you write to us about a call: it is also returned in the X-Request-Id header on every response, successes included.

{
  "error": {
    "code": "site_not_found",
    "message": "site_not_found",
    "requestId": "70b0b670-ecb1-4ceb-b8a0-9096b8b56ee3"
  }
}

code is stable and meant for calling code; message is for a human and may change without notice. Do not build logic on the message.

HTTPMeaningExamples
401Key or token missing, malformed, expired or revokedunauthenticated, invalid_token
403Refused: the user’s role (OAuth token), a test key on a write, or a key created before full access — open it in Settings → Developers and saveforbidden, test_key_read_only
404Resource not found in the organisationclient_not_found
400Validation (including a field the body should not carry, or a number that is not one) or business rulevalidation_failed, service_required, invalid_range, owner_required
402ERP modules missing from the workspace’s planerp_required
403Offer switched off on the platform (e.g. ERP)offer_disabled
409Conflict with what exists (a SIRET already used, on /clients and /companies alike)schedule_conflict, siret_already_used
429Workspace budget exhaustedrate_limited

Rate limits

The budget belongs to the workspace, and all of its API keys and OAuth tokens spend the same one. The people using the dashboard each have their own, so an integration that loops cannot lock its own customer out.

WindowPer workspace, all keys and tokens togetherHeaders
1 minute600 requestsX-RateLimit-Limit, -Remaining, -Reset (seconds)
24 hours50,000 requestsX-RateLimit-Limit-Day, -Remaining-Day, -Reset-Day

These are the defaults; Iwana staff can change them platform-wide, so read the X-RateLimit-Limit* headers rather than hard-coding the numbers. Past either window the answer is 429 with the usual envelope, error.code = "rate_limited", and a Retry-After header in seconds. A per-IP floor of 1,000 requests/minute also applies before authentication, under the same unsuffixed header names: a call refused by the credential or permission checks (401, a 403 such as test_key_read_only, a 402) carries only those per-IP headers — no -Day ones — and does not spend the workspace budget.

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 12

{ "error": { "code": "rate_limited", "message": "…", "requestId": "…" } }

Pace on X-RateLimit-Remaining and back off on 429. Refresh access tokens at the hour mark, not per request.

Versioning

Current version: v1 (/api/v1/pro/…). Breaking changes will be published under /v2/ with an overlap of at least 12 months on v1.

Backwards-compatible additions (new optional fields, new endpoints) may arrive without a major version bump. Treat unknown fields in a response as normal: your client must not fail because we added one. In a request it is the other way round: an undeclared field is refused with 400 validation_failed.

OpenAPI

This whole page also exists in machine-readable form, and more complete: the specification lists every operation a key can call — nearly 300 — with its parameters, body and response. Paste this URL into Postman, Insomnia, Swagger UI or an SDK generator — you do not have to copy the schemas by hand.

curl https://iwana.fr/v3/api/v1/openapi.json

Interactive reference (Swagger) Open openapi.json

The document is served without authentication: a specification you need a key to read is a specification nobody evaluates before signing up. It only describes shapes — no workspace data passes through it.

Prompts for AI agents

Building the integration with Claude, Cursor, Copilot or another coding agent? These prompts give it the exact API contract so it does not have to guess. Copy, replace what is in angle brackets, paste.

Always start with the context sheet: it fits in a system message or at the top of a conversation, and every task prompt builds on it.

Context sheet — paste before any task

The facts the agent must know so it invents nothing: URL, authentication, error envelope, limits, where to read the full contract.

You will help me integrate the Iwana REST API (a booking SaaS for building-trade professionals, France/EU). Here is the contract; assume nothing that is not in it — read the OpenAPI specification first.

- OpenAPI specification (source of truth for every schema): https://iwana.fr/v3/api/v1/openapi.json
- Human documentation: https://iwana.fr/developers/api
- Base URL: https://iwana.fr/v3/api/v1/pro — every route below is relative to this prefix.
- Authentication: header "Authorization: Bearer <token>". Two token forms, same routes, same permissions:
  - a workspace API key "iw_live_…", created in Settings → Developers; a test key "iw_test_…" reads the same real workspace and is refused every write (403 test_key_read_only, before the body is validated) — no separate demo workspace exists;
  - an OAuth 2.0 access token "iwa_at_…" obtained through Authorization Code (authorize: https://iwana.fr/v3/oauth/authorize; token: POST https://iwana.fr/v3/api/v1/oauth/token as form-urlencoded; identity: GET https://iwana.fr/v3/api/v1/oauth/userinfo). Access token 1 h, refresh token 3 years and unchanged on refresh, PKCE S256 optional.
- No x-workspace-id header: the token carries the workspace.
- Health check: GET /integrations/me returns orgId, actor, permissions, locale, timezone.
- A key or a token opens the whole API in the specification (appointments, clients, sites, equipment, contracts, catalogue, team, quotes, invoices, interventions, projects, tasks, workflows, settings). A 403 means the user's role (OAuth token) or a test key (read-only) refuses the action. A key never calls the AI. A 402 erp_required means the workspace's plan lacks the ERP modules; a 403 offer_disabled means the offer is switched off for the whole platform.
- Errors: always { "error": { "code": "…", "message": "…", "requestId": "…" } }. "code" is stable, "message" is not: never branch on "message". X-Request-Id is present on every response.
- Limits: 600 requests/minute and 50,000/day per workspace, shared by all of its keys and tokens. Read X-RateLimit-Remaining and X-RateLimit-Remaining-Day; on 429, honour Retry-After (seconds). A 401/403 refused before the workspace budget is counted carries only the per-IP X-RateLimit-* headers, without the -Day ones.
- Retries: send an Idempotency-Key header (8 to 128 characters) on create POSTs (appointments, clients, contacts, companies, sites, equipment, contracts, quotes, invoices, payments, interventions, projects, tasks); the same key on the same route within 48 h returns the first response instead of creating a duplicate.
- Duplicates: POST /clients without an id always creates, it never matches on email or phone. Store the mapping between my IDs and Iwana's with PUT /external-refs { provider, entityType, localId, externalId } and resolve it with GET /external-refs?provider=&entityType=&externalId= before creating; without a match the answer is { "item": null } (200, not 404).
- Lists: each operation has its own page size and shape ({ items, total } with or without limit/offset, { items } or an array): read it in the specification, do not assume.
- Dates are ISO 8601 UTC; amounts named "…Cents" are cents. An undeclared field in a request body: 400 validation_failed, so send only the schema's fields. Unknown fields in a response: ignore them, never fail.
- Incoming webhooks: signed JSON POST; headers Iwana-Signature (sha256=<HMAC-SHA256 of the raw body>), Iwana-Event, Iwana-Delivery. Verify the signature on the RAW body, answer 2xx within 15 s, process asynchronously. A single delivery attempt with no automatic retry: plan a periodic reconciliation through the list endpoints.
- Never log a key, a client secret or a token.

The system I am connecting: <CRM / ERP / tool>.

1. Sync clients and appointments with an API key

A two-way, idempotent sync that respects the rate limits.

Using the Iwana context sheet above, implement a two-way sync between <my system> and Iwana with a workspace API key.

Requirements:
1. On start-up, call GET /integrations/me and stop with a clear message if the permissions do not include what the sync needs.
2. Read the catalogue (GET /catalog/services) and the team (GET /team) once and cache them to map my service and staff IDs.
3. For every contact in <my system>: first resolve GET /external-refs?provider=<my-provider>&entityType=client&externalId=<id>; if item is null, POST /clients (with an Idempotency-Key derived from my id) then PUT /external-refs; otherwise POST /clients with the Iwana id to update. Iwana does not match on email: never create the same contact twice.
4. Same pattern for appointments (POST /appointments with serviceId, clientId, startAt/endAt in ISO 8601 UTC, memberIds, customFields.<myId>, and an Idempotency-Key). On an update, always send startAt and endAt again.
5. Respect the budget: read X-RateLimit-Remaining, slow down when it drops below 10%, and on 429 wait Retry-After before retrying. Never retry a 400 or a 403.
6. Log the requestId of every error, never the key.

Start by listing the endpoints you will call and in what order, then implement.

2. Implement “Sign in with IWANA” (OAuth 2.0)

For a product several businesses install: the user authorises your app, you get a token per workspace.

Using the Iwana context sheet above, implement “Sign in with IWANA” (Authorization Code with a client secret, PKCE S256 enabled).

Contract:
- Redirect the user to https://iwana.fr/v3/oauth/authorize?client_id=<CLIENT_ID>&redirect_uri=<URI registered, exact match>&response_type=code&state=<random>&code_challenge=<S256>&code_challenge_method=S256
- Back on redirect_uri: check state; if ?error=access_denied, show a message and exchange nothing. The code (iwa_ac_…) lives 60 s and works once.
- Exchange: POST https://iwana.fr/v3/api/v1/oauth/token, Content-Type application/x-www-form-urlencoded, grant_type=authorization_code&code=…&redirect_uri=<same value>&client_id=…&client_secret=…&code_verifier=…
  Response: { access_token: "iwa_at_…", token_type: "Bearer", expires_in: 3600, refresh_token: "iwa_rt_…", scope: "…" }
- Identity: GET https://iwana.fr/v3/api/v1/oauth/userinfo with the bearer → { sub, email, name, org_id, org_name, role, scope }. Link my user account to the pair (sub, org_id).
- Refresh: grant_type=refresh_token&refresh_token=…&client_id=…&client_secret=… → new access_token, the refresh_token stays the same. Refresh on expiry (1 h), not per request.
- Token endpoint errors: { error, error_description } with invalid_request, invalid_client (401), invalid_grant, unsupported_grant_type. On invalid_grant during refresh, the grant was revoked or expired: mark the connection as needing re-authorisation and send the user back through authorize.
- A 401 invalid_token on an API route with a non-expired access token means the workspace revoked the app: same treatment.
- Keep access_token, refresh_token, expires_at, sub and org_id per connection; never log a token or the client secret.

Handle every case above: invalid state, access_denied, code expiry, token expiry and revocation.

3. Receive webhooks and verify the signature

An HTTPS endpoint that checks the HMAC on the raw body, answers fast and processes in the background.

Using the Iwana context sheet above, implement an Iwana webhook receiver.

Delivery contract:
- JSON POST to my HTTPS URL. Headers: Iwana-Signature: sha256=<hex HMAC-SHA256 of the raw body with my subscription secret>, Iwana-Event: <type>, Iwana-Delivery: <uuid unique per attempt>.
- Body: { "event": "appointment.created", "orgId": "…", "data": { "id": "…", "startAt": "…", "status": "…" }, "occurredAt": "…" }
- Events: the current list is x-iwana-webhook-events in https://iwana.fr/v3/api/v1/openapi.json (for example appointment.created, appointment.cancelled, client.updated); data always carries the record's id, with related ids, the status, ISO dates and amounts in cents.
- One attempt per event, 15 s timeout, no automatic retry: a missed event must be caught up by reconciliation.

Requirements:
1. Read the RAW body (before any JSON parsing) and compare the HMAC in constant time; answer 401 if the signature does not match.
2. Answer 2xx immediately after queuing the event; process asynchronously.
3. Process each Iwana-Delivery once (store processed IDs) as a precaution.
4. For every event, reload the full object with the matching GET (GET /appointments/{id}, GET /clients/{id}…) rather than trusting the partial payload; ignore event types you do not handle.
5. Never log the subscription secret.
6. Add a periodic reconciliation (GET /appointments?from=&to=, GET /clients) to catch up on missed events.

4. Build a client from the OpenAPI specification

Do not transcribe the schemas: the agent reads the public specification and builds the client from it.

Using the Iwana context sheet above, build a client for the Iwana PRO API from its OpenAPI specification.

1. Download https://iwana.fr/v3/api/v1/openapi.json and keep only the paths starting with /pro/: they are relative to the base URL https://iwana.fr/v3/api/v1 (the OAuth routes https://iwana.fr/v3/api/v1/oauth/token and https://iwana.fr/v3/api/v1/oauth/userinfo are not in it, they are described above).
2. Derive every request and response type from the specification rather than writing them by hand, so the client can be regenerated when the specification changes.
3. The client must: inject "Authorization: Bearer <token>", read X-RateLimit-Remaining and wait Retry-After on 429, turn the { error: { code, message, requestId } } envelope into a typed error carrying code and requestId, and ignore unknown fields.
4. Verify the client against the real API with GET /integrations/me using an iw_test_ key I provide.

Show me the list of retained operations first, then the client.

Ready to integrate?

Create your first key in the dashboard, or write to us to register an OAuth app.

Your cookies

We use cookies that are strictly necessary to run the service. With your consent we also switch on monitoring cookies (Sentry) to diagnose incidents. Read more in our cookie policy.