Connect your tool to The Big One.

In The Big One, an administrator creates a token from Settings › Integrations › Developer access, choosing its permissions: read (reading), write (writing), import (batch upload), billing (invoicing, never ticked by default). The token is shown only once; create one per tool so you can revoke them separately.

Every call carries the token in the Authorization header. The company is deduced from the token: no company ID to send.

Token limited to some properties. To give a key to a client or a partner, choose “Some properties” in the token window: a client (the properties it is the client of today, which follow automatically), buildings, tags or chosen properties; the choices add up. The token then only reads what concerns those properties (jobs, bookings, issues, reviews, deliveries, linen), and only the buildings of those properties. The team, time off, linen orders and the delivery log answer 403; sectors are limited to those of its properties; a job or a property outside the limit answers 404. A limited token never has import, and billing requires a client: it then only reads that client's details, prices and reports.

Complete schema. The OpenAPI 3.1 schema of the whole API (routes, parameters, responses, notifications) can be downloaded without a token: https://thebigone.io/api/public/v1/openapi.json. Its version is the date of the latest change, described in the changelog at the bottom of this page.

curl https://thebigone.io/api/public/v1/tasks?from=2026-10-01&to=2026-10-07 \
  -H "Authorization: Bearer cnimp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Fields are in English and camelCase, identical when sending and reading. Every item you send carries your own identifier, externalId: sending the same identifier again updates the item instead of creating a duplicate.

Listing photos. In a batch upload, each property can carry photos: https:// links (or { url, caption, thumbnailUrl }), the first one being the main photo, 60 at most. They appear on the property sheet, for the office and for cleaners. Without the field, nothing changes; [] removes them.

{ "properties": [ {
  "externalId": "LOG-12",
  "name": "Bastille — 3 pièces",
  "photos": [
    { "url": "https://photos.votre-outil.fr/log-12/salon.jpg", "caption": "Salon" },
    "https://photos.votre-outil.fr/log-12/chambre.jpg"
  ]
} ] }

Lists return { data, nextOffset, limit, offset }. As long as nextOffset is not null, call again with offset=nextOffset (100 items by default, 500 at most). For a sync, store the time of your last call and pass it in updatedSince.

Job filters: from, to, status (created, assigned, in_progress, completed, cancelled), type, propertyExternalId, validated, updatedSince. Cancelled jobs (cancelled, not shown in the planning) are only returned with status=cancelled or includeCancelled=true; each job carries inPlanning. Add include=report,checklist,comments to get, in a single call, the report content, the checklist and the comments of each job (50 jobs per page at most with checklist).

{
  "id": "0b9d2c7e-4a6f-4c1e-9f2a-1d3e5b7c9a01",
  "externalId": "MEN-881",
  "type": "cleaning",
  "date": "2026-11-07",
  "startTime": "11:00:00",
  "timezone": "Europe/Paris",
  "startAt": "2026-11-07T11:00:00+01:00",
  "plannedDurationMinutes": 150,
  "plannedEndAt": "2026-11-07T13:30:00+01:00",
  "status": "completed",
  "inPlanning": true,
  "assignees": ["Camille"],
  "startedAt": "2026-11-07T10:12:00Z",
  "endedAt": "2026-11-07T12:05:00Z",
  "completedAt": "2026-11-07T12:05:04Z",
  "validated": true,
  "validatedAt": "2026-11-07T14:20:00Z",
  "property": { "id": "…", "name": "Bastille — 3 pièces", "externalId": "LOG-12" },
  "reservation": { "id": "…", "code": "HMX4K2", "platform": "guesty", "checkoutAt": "2026-11-07T11:00:00+01:00" },
  "nextArrival": { "id": "…", "code": "HMQ81Z", "platform": "guesty", "checkinAt": "2026-11-07T15:00:00+01:00", "guests": 4 },
  "reportUrl": "https://thebigone.io/task/report/…",
  "reportReadyAt": "2026-11-07T12:05:04Z",
  "report": { "summary": { "status": "to_report", "toReport": 2, "checklistItems": 38, "checklistDone": 37 },
    "notDone": [ { "label": "Four : intérieur", "section": "Cuisine", "required": true } ],
    "issues": [ { "category": "leak", "status": "new", "urgent": true } ],
    "inspection": null, "inventory": [], "linenMoves": [] },
  "updatedAt": "2026-11-07T14:20:01Z"
}

Times, report and guests. Each job carries timezone (time zone of the property), startAt and plannedEndAt (full date and time with their offset, for example 2026-11-07T11:00:00+01:00), plannedDurationMinutes, completedAt and validatedAt. endedAt is the end clocked by the cleaner, otherwise the moment the job was completed. As soon as a job is completed, reportUrl is filled and reportReadyAt tells since when the report can be viewed. reservation gives the linked stay (booking code, platform: source software, checkinAt, checkoutAt) and nextArrival the next guest arrival in the property.

Job details. GET /api/public/v1/tasks/:id gives everything at once: report (report content), checklist (each checklist line with done, note, value, its photos and its referencePhotos) and comments. Photo links are valid for 7 days; the report link (reportUrl) stays valid for 90 days.

Report content. report.summary.status is ok or to_report, and toReport counts the required items not done, the issues reported during the job and an inspection to redo. The details follow: notDone, notes, issues, inspection (check done, result: compliant or redo, score and remark), inventory (linen and consumables counted during the job: missing, stained, broken) and linenMoves.

"checklist": {
  "name": "Ménage classique",
  "items": [ {
    "id": "…", "label": "Salle de bains : miroir et robinetterie", "section": "Salle de bains",
    "required": true, "kind": "checklist", "done": true, "note": null, "value": null,
    "photos": [ { "url": "https://…", "thumbnailUrl": "https://…", "takenAt": "2026-10-05T12:41:00Z" } ],
    "referencePhotos": []
  } ]
}

Deleted jobs. GET /api/public/v1/tasks/deleted?since=… lists the jobs deleted since that moment (kept for 90 days): a job missing from a page is never mistaken for a deleted job. A job restored from the bin leaves this list and comes back in /tasks.

Booking filters: from, to, status (confirmed, cancelled, blocked — closed dates with no guest), propertyExternalId, updatedSince. Reported issues: from, to (day reported), status (new, in_progress, resolved), urgent, taskId, propertyExternalId, updatedSince. Guest reviews: from, to, taskId, propertyExternalId, updatedSince; ratings are scaled to 5, the original rating stays in ratingRaw and ratingScale.

{
  "id": "7c1e…",
  "category": "leak",
  "urgent": true,
  "description": "Fuite d'eau sous le lavabo",
  "status": "new",
  "reporterName": "Camille",
  "reportedAt": "2026-10-05T12:50:00Z",
  "taskId": "0b9d2c7e-4a6f-4c1e-9f2a-1d3e5b7c9a01",
  "property": { "id": "…", "name": "Bastille — 3 pièces", "externalId": "LOG-12" },
  "photos": [ { "url": "https://…", "thumbnailUrl": "https://…" } ]
}

Issue categories (category): damage, breakdown, dirt, linen, pests, access, leak, other.

Team. GET /api/public/v1/people returns for each person id, name (planning name), email, role and roles, activities (cleaning, linen, inspection, delivery, maintenance), sectors and availability: days from 1 (Monday) to 7 (Sunday), start and end times, maxHours when a cap is set for the person. Filters: role, activity. Phone number, address, contract and pay are never returned. GET /api/public/v1/time-off: from, to (leave overlapping the period), status (requested, approved, refused), personId, updatedSince; a pending change or cancellation request is in changeRequest.

{
  "id": "5d2f…",
  "name": "Camille",
  "planningName": "Camille",
  "fullName": "Camille Martin",
  "email": "camille@…",
  "role": "agent",
  "roles": ["agent"],
  "activities": ["cleaning", "linen"],
  "sectors": [ { "id": "…", "name": "Paris Est" } ],
  "availability": [ { "weekday": 1, "startTime": "08:00", "endTime": "16:00", "maxHours": 7 } ]
}

Properties. Each property carries propertyType, capacity, bedrooms, bathrooms, timezone, sector, building, tags and client (the current client, from the rates, as on the invoice). List filters: active, sectorId, tag, updatedSince. GET /api/public/v1/properties/:id adds amenities, listingPhotos and sheet: the sections of the property sheet and their filled-in fields. The “Access” section (codes, key box…) is not returned by the API.

Address. Each property also carries addressDetails: street, postalCode, city and full, the address of the property itself read from its sheet, never the building's.

{
  "id": "…",
  "externalId": "LOG-12",
  "name": "Bastille — 3 pièces",
  "address": "17 rue de la Roquette",
  "addressDetails": { "street": "17 rue de la Roquette", "postalCode": "75011", "city": "Paris", "full": "17 rue de la Roquette 75011 Paris" },
  "propertyType": "apartment",
  "capacity": 6, "bedrooms": 2, "bathrooms": 1,
  "sector": { "id": "…", "name": "Paris Est" },
  "building": { "id": "…", "name": "12 rue de la Roquette", "address": "12 rue de la Roquette, 75011 Paris" },
  "tags": ["Premium"],
  "client": { "id": "…", "name": "Habitat Parisien" },
  "sheet": [ { "label": "Le logement", "role": "housing",
    "fields": [ { "id": "…", "label": "Surface", "value": "65 m²", "role": "surface" } ] } ]
}

Linen and deliveries. Each linen line carries place (type: depot, building or property), article and source (company, laundry, client). GET /api/public/v1/linen/stock: filters placeType, article, updatedSince. GET /api/public/v1/linen/moves: from, to, kind (count, delivery, taken, office, prepared, cleaning, move, receipt), placeType, article; each move gives before, after and delta. GET /api/public/v1/linen/orders: from, to, status (draft, sent, received), without prices. GET /api/public/v1/deliveries: from and to required (31 days at most), driver, propertyExternalId; each delivery gives arrivedAt, departedAt, completedAt and its proofs (links valid for 7 days).

{
  "id": "…",
  "date": "2026-11-04",
  "time": "09:30",
  "property": { "id": "…", "name": "Bastille — 3 pièces", "externalId": "LOG-12" },
  "driver": "Yanis",
  "arrivedAt": "2026-11-04T08:41:00Z",
  "departedAt": "2026-11-04T08:47:00Z",
  "completedAt": "2026-11-04T08:47:10Z",
  "proofs": [ { "url": "https://…", "takenAt": "2026-11-04T08:46:00Z", "note": null } ]
}

Invoicing. These endpoints only answer a token with the billing (Invoicing) box ticked; it is never ticked by default: only tick it for your own tools or your accountant. GET /api/public/v1/clients: identity, contact, billing addresses (billingEmails), SIREN, VAT number and today's tax rate (tax.source: client, company, exempt or reverseCharge); includeDeleted=true adds clients moved to the bin. GET /api/public/v1/prices: base rate of each property, its periods and, in onDate, the rate that applies on day date (today by default); filter clientId. GET /api/public/v1/reports: reports and invoices (filters from and to in YYYY-MM format, clientId), with status (checked, invoiced, sent, paid), totals, finalised credit notes, net amount due and payment (null until the invoice is finalised). GET /api/public/v1/reports/:id adds the lines exactly as they were invoiced. Amounts are the software's own, never recalculated.

{
  "id": "…",
  "number": 12,
  "clientId": "…",
  "month": "2026-10",
  "period": null,
  "status": "sent",
  "currency": "EUR",
  "totals": { "ht": 1250, "tax": 250, "ttc": 1500 },
  "net": { "invoicedHt": 1250, "invoicedTtc": 1500, "creditHt": 50, "creditTtc": 60, "netHt": 1200, "netTtc": 1440 },
  "creditNotes": [ { "id": "…", "number": "AV-2026-014", "date": "2026-11-03", "amountHt": 50 } ],
  "sentOn": "2026-11-02",
  "payment": { "status": "toPay", "paidOn": null, "dueDate": "2026-12-02", "daysLate": 0 },
  "lines": [ { "apartment": "Bastille — 3 pièces", "date": "2026-10-05", "description": "Ménage",
    "quantity": 1, "amountHt": 100, "baseHt": 80,
    "adjustments": { "linen": { "count": 2, "amount": 20 }, "hours": null, "other": 0 },
    "manual": false, "taskId": "0b9d2c7e-…" } ]
}

POST /api/public/v1/tasks creates a job with the same fields as the import (externalId, propertyExternalId, date, type, startTime, durationHours, assigneeName, notes…). Response 201 if it is created, 200 if it already existed and has been updated.

curl -X POST https://thebigone.io/api/public/v1/tasks \
  -H "Authorization: Bearer cnimp_…" -H "Content-Type: application/json" \
  -d '{"externalId":"MEN-882","propertyExternalId":"LOG-12","date":"2026-10-06","type":"cleaning","startTime":"11:00"}'

PATCH /api/public/v1/tasks/:id changes date, startTime, durationHours, assigneeName, notes, needsDelivery or needsKit. A job that has already started, finished or been approved is never changed: the response is then 409.

Add your tool's HTTPS address in Developer access and choose the events. The Big One sends a JSON POST request to it within the next minute:

• task.created — job created
• task.assigned — job assigned
• task.started — job started
• task.completed — job completed
• task.validated — job approved by a manager
• task.updated — job changed: date, time, duration, cleaner, notes, property… (data.changes)
• task.cancelled — job cancelled (it leaves the schedule)
• task.deleted — job deleted (data.task: its last known form)
• task.comment_added — comment added to a job (data.comment)
• report.ready — job report available (reportUrl and report)
• inspection.completed — quality control done (result, score and remark in report.inspection)
• issue.reported — issue reported by a cleaner (data.issue)
• issue.updated — issue taken in hand or resolved (data.issue)
• issue.resolved — issue resolved: time to tell the client “it's fixed”
• reservation.created — booking created (data.reservation)
• reservation.updated — booking changed: dates, times, property or number of guests
• reservation.cancelled — booking cancelled, or removed by the property management system (removed: true)
• property.created — property created (data.property)
• property.updated — property changed, including its client from the rates (data.property, data.changes)

POST https://votre-outil.fr/hooks/thebigone
X-TheBigOne-Event: task.completed
X-TheBigOne-Delivery: 5f1c…
X-TheBigOne-Signature: t=1790000000,v1=9a3f…

{ "id": "5f1c…", "type": "task.completed", "createdAt": "2026-10-05T13:05:02Z",
  "data": { "task": { …la mission, au format de la lecture… } } }

Reply with a 2xx code within 10 seconds. Otherwise, delivery is retried after 1, 5, 15, 60 and then 240 minutes, then abandoned. X-TheBigOne-Delivery identifies the delivery: use it to ignore a duplicate.

Check the signature with the secret shown when the address is created: HMAC-SHA256 of <t>.<raw body>, and reject a timestamp older than 5 minutes.

import crypto from "node:crypto";

function signatureValide(secret, corpsBrut, entete) {
  const t = /t=(\d+)/.exec(entete)?.[1];
  const v1 = /v1=([0-9a-f]+)/.exec(entete)?.[1];
  if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const attendu = crypto.createHmac("sha256", secret).update(`${t}.${corpsBrut}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(attendu), Buffer.from(v1));
}

Delivery log. GET /api/public/v1/webhook-deliveries lists the deliveries (pending, sent, given up), with the number of attempts, your server's last response and the time of the next attempt. In Developer access, “Send a test” sends a test.ping event to the chosen address.

• Per address: 1,200 reads and 300 writes per 10 minutes. Per token, all addresses combined: 1,200 calls per 10 minutes. Beyond that, the 429 response carries a Retry-After header (seconds to wait). To make fewer calls: include= on the job list, and notifications.
• Import: 5 MB per call, 2,000 items per type, 60 calls per 10 minutes per company.
• Dates in YYYY-MM-DD format. Times alone (HH:MM) are in the local time of the property (timezone field); startAt, plannedEndAt, checkinAt and the other timestamps are complete, with their offset or in UTC (ISO 8601).

400 invalid parameters or body · 401 token missing or invalid · 403 permission missing · 404 not found · 409 job locked · 413 body too large · 422 line rejected · 429 too many calls · 503 service temporarily unavailable. All errors have the form { "error": "…" }.

An integration question? See the Custom source page or write to us using the form below.

Any change that may affect a connected tool is dated here. The OpenAPI schema version (info.version) is the date of the latest one.

• 7 November 2026. Cancelled jobs: status cancelled, no longer returned by default (before, they came out as created); field inPlanning. reportUrl always filled for a completed job; completedAt, reportReadyAt; endedAt filled even without clocking. Full times with time zone (timezone, startAt, plannedEndAt), linked stay (reservation) and next arrival (nextArrival). include=report,checklist,comments and report content as data. Routes /tasks/deleted, /webhook-deliveries and /openapi.json. Property address (addressDetails). Ten new notifications. Photo links valid for 7 days. /sectors open to a limited token (its sectors). Higher limits.
• 3 November 2026. Checklist and photos of a job, reported issues, guest reviews, team and time off, complete properties, sectors and buildings, linen and deliveries, invoicing (billing scope); token limited to some properties; four notifications (issue reported, booking created, changed, cancelled); per-token limit.
• 27 September 2026. First version: batch import, reading jobs, properties and bookings, creating and changing a job, tokens by use, signed notifications.