Accesso API: turni, ore e assenze
Questa pagina esiste in francese, ucraino e inglese: ecco la versione inglese.
What it is for
API access lets your accounting, payroll or CRM software automatically read your company's published schedule, everyone's hours and approved absences. The “SF” pack gives read access; the “SF Pro” pack also allows writing (see below).
API access is included in the subscription, taken out in the web version (app.staff-flow.cloud): Configuration → Manage subscription. Read access is open during the free trial.
1. Create a key
In the app, the company owner (or a manager entrusted with the subscription) opens Configuration → API access → New key and gives it a name (for example “Payroll software”). The full key is shown only once: copy it into your software. You can set it aside or revoke it at any time.
2. Call the API
Send the key in the “Authorization: Bearer …” header (or “X-Api-Key”). All addresses start with https://app.staff-flow.cloud/api/v1/ext/.
curl -H "Authorization: Bearer sfk_xxxxxxxx_yyyyyyyy…" \
"https://app.staff-flow.cloud/api/v1/ext/shifts?from=2026-10-01&to=2026-10-31"
3. Endpoints
GET /api/v1/ext/company company, sites, positions, teams (with members)
GET /api/v1/ext/members people (current and former), role, rank, dates
GET /api/v1/ext/roles role hierarchy: names, ranks, privileges
GET /api/v1/ext/shifts published shifts ?from=&to=&format=csv
GET /api/v1/ext/totals published hours/person ?from=&to=&format=csv
GET /api/v1/ext/absences approved leave and unavailability ?from=&to=
Period: “from” and “to” as YYYY-MM-DD. Without “from”, since the company was created; without “to”, up to today; 5 years at most per call.
Format: JSON by default ({"data": […]}); add “format=csv” for a CSV file (“;” separator, opens in Excel).
Only the published schedule is returned (what employees see), never drafts.
4. Sample response
{
"data": [
{
"id": "6c1f…", "day": "2026-10-06", "start": "08:00", "end": "16:00",
"minutes": 480, "userId": "a41e…", "userName": "Olena",
"siteId": "…", "site": "Centre", "positionId": "…", "position": "Barista",
"note": null
}
]
}
5. Errors
401: missing, wrong or revoked key. 402: the “API access” option is not active (subscription without the option). 400: invalid dates.
API Pro: writing into Staff Flow
With the “SF Pro” pack (paid subscription; not during the trial or the grace period), your software can also send schedules, employees, positions and sites, announcements and clock-ins, and approve requests.
Each key has its own permissions, feature by feature, read or write: company (positions and sites), employees, schedule, publishing, absences, requests, announcements, clock-in, payroll, polls, signature tracking. Permissions can be changed without changing the key. Only the owner and managers with the “API keys” privilege create, set aside and revoke keys. If the subscription stops, keys stop working and are deleted after 30 days (you are warned 7 days before).
POST /api/v1/ext/shifts create shifts (draft, or "publish": true)
PATCH /api/v1/ext/shifts/{id} edit a shift (back to draft)
DELETE /api/v1/ext/shifts/{id} delete a shift
POST /api/v1/ext/publish publish all drafts
POST /api/v1/ext/members/import import employees -> invitations with codes
GET /api/v1/ext/invites pending invitations (code, QR link)
PUT /api/v1/ext/members/{ref}/profile employee number, position
POST /api/v1/ext/positions new position {"name": "…"}
POST /api/v1/ext/sites new site {"name": "…", "parent": "…"}
POST /api/v1/ext/teams new team {"name": "…"}
PUT /api/v1/ext/teams/{team}/members/{ref} add a person to a team
DELETE /api/v1/ext/teams/{team}/members/{ref} remove a person from a team
POST /api/v1/ext/news announcement {"title", "body", "audience"}
GET /api/v1/ext/requests pending requests
POST /api/v1/ext/requests/{id}/approve | refuse
GET /api/v1/ext/clock clock-in events ?from=&to= [clock]
POST /api/v1/ext/clock forgotten clock-in/out {"person", "at", "kind": "in"|"out", "note"} [clock]
POST /api/v1/ext/clock/badge badge read by a reader {"badge", "site"} → arrival or departure [clock]
GET /api/v1/ext/timesheet planned / clocked minutes, leave ?from=&to= [clock]
GET /api/v1/ext/coverage/gaps time slots short of people ?from=&to= [shifts]
POST /api/v1/ext/coverage minimum people per time slot {"weekdays", "start", "end", "min", "site", "position"} [catalog]
GET /api/v1/ext/payroll payroll preview (indicative) ?from=&to=&planned=1 [payroll]
GET /api/v1/ext/polls polls and results [polls]
POST /api/v1/ext/polls new poll {"question", "options", "multi", "anonymous", "audience"} [polls]
GET /api/v1/ext/signatures signature tracking (no signature image, IP or device) [documents]
GET /api/v1/ext/signatures/{id}/zip closed request: signed PDF + certificate (ZIP) [documents]
Shifts you send arrive as drafts: managers see them, adjust them, then publish. With the “publish” permission and "publish": true, they are published at once. A person is given by their SF ID or employee number; a site or position by its name or id. With "team" (a team name or id) instead of "person", each member of the team gets their shift; an announcement can also target teams ("teams" in "audience"). Times: “HH:MM” or minutes since midnight.
POST /api/v1/ext/shifts
{
"publish": false,
"shifts": [
{"day": "2026-10-20", "start": "07:00", "end": "15:00",
"person": "M-0007", "site": "Chantier Nord", "position": "Maçon"},
{"day": "2026-10-20", "start": "07:00", "end": "15:00",
"team": "Groupe 1", "site": "Chantier Nord",
"location": {"lat": 48.8584, "lng": 2.2945, "label": "12 rue du Chantier"}}
]
}
Errors: 403 if the key lacks the permission, 402 if the “API Pro” option isn't active, 400 if a person, site or time is unknown. Every write is logged in the company history with the key's name.
MCP connector: Staff Flow in your assistant
Assistants that support MCP (Model Context Protocol), such as Claude, connect straight to Staff Flow. You write, for example: “Put Marie on the till Monday from 8 to 4” or “How many hours did the team work in September?”.
Adresse / URL : https://app.staff-flow.cloud/api/v1/mcp
En-tête / Header : Authorization: Bearer sfk_…
get_company · list_members · get_roles · get_shifts · get_hours · get_absences
create_shifts · update_shift · delete_shift · publish_schedule
import_employees · list_invitations · set_employee_profile
create_position · create_site · create_team · add_to_team · remove_from_team
post_announcement
list_pending_requests · decide_request
get_clock_events · add_clock_event · get_timesheet
get_coverage_gaps · add_coverage_rule · get_payroll_preview
list_polls · create_poll · list_signatures
Add a custom connector with this address and an API key. The assistant only sees the tools the key's permissions allow: reading with the “API access” option, writing with “API Pro”. Shifts it creates arrive as drafts unless the key has the “publish” permission. Every action is logged in the history with the key's name.
Full guide, tool by tool: https://staff-flow.cloud/en/mcp/
Webhooks: Staff Flow notifies your software
With the “API Pro” option, Staff Flow sends a message on its own (JSON POST) to your software's address when something happens. No more polling the API.
In the app: Configuration → API access → Webhooks. The owner and managers entrusted with the subscription add up to 5 addresses (https), choose the events, and can send a test delivery.
schedule.published planning publié / schedule published
request.created nouvelle demande / new request
request.decided demande validée ou refusée / approved or refused
request.cancelled demande annulée / request cancelled
request.cancel_asked annulation de congé demandée / leave cancellation asked
request.cancel_decided annulation de congé décidée / leave cancellation decided
request.ended indisponibilité terminée / unavailability ended
member.joined nouveau salarié / new employee
member.role_changed rôle changé / role changed
member.privileges_changed privilèges changés / privileges changed
team.member_added ajouté à une équipe / added to a team
team.member_removed retiré d'une équipe / removed from a team
announcement.published annonce publiée / announcement published
POST https://votre-logiciel.example/staff-flow
Staff-Flow-Event: request.decided
Staff-Flow-Delivery: 6f1c…
Staff-Flow-Signature: t=1792400000,v1=5d2a…
{
"id": "6f1c…",
"event": "request.decided",
"createdAt": "2026-10-13T08:12:00Z",
"company": {"id": "SF-…", "name": "Boulangerie"},
"data": {"kind": "leave", "approved": true, "from": "2026-11-02", "to": "2026-11-03",
"person": {"sfId": "SF-…", "name": "Marie", "employeeNumber": "M-0007"}}
}
v1 = HMAC-SHA256(secret, t + "." + body) (hex)
Every delivery is signed with the secret given at creation (shown only once): recompute the signature and compare, then reject timestamps older than 5 minutes. Answer with a 2xx code within 10 seconds.
On failure, Staff Flow retries after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h. After 10 dropped deliveries in a row, the address is turned off; you turn it back on in the app. People are identified by their SF ID and employee number, never by email address. Option ended or grace period: nothing is sent any more.
Logs and alerts
Every call from your keys (read, write, MCP assistant) and every webhook delivery is logged: date, key, plain-language action, result, duration, IP address. For an edit, the before and after (“start 08:00 → 09:00”).
In the app: Configuration → API access → Logs. One month at a time (swipe to change), search (person, employee number, action) and filters (key, source, read or write, succeeded or failed). For the owner and managers entrusted with the subscription.
The last 12 months stay online; older months are archived automatically and can still be browsed and searched (“search the whole history”). Each year can be downloaded as a ZIP (one CSV file per month, opens in Excel). Logs are deleted after 3 years.
The owner is alerted if a key fails 10 times in one hour, or is used from a new IP address (a possible sign of a stolen key). Each key shows its calls today and this month. A key's permissions can be changed without changing the key.
Personal data
The company remains responsible for how it uses the data it retrieves (names, hours, absences) and must protect it in its own software. Keep keys secret; revoke a key as soon as it is no longer used.