{"openapi":"3.0.3","info":{"title":"Bizisy API","version":"aa4f9f25f02c","description":"The Bizisy API: every action in the product, one HTTP call each. The same definitions power the web app and the MCP endpoints, so the API never lags behind.\n\nAuthenticate with an API key (Authorization: Bearer hrk_…), created in Manage → Settings (manage keys) or in the employee app under Connect AI (me keys). The key decides the company.\nWrites accept ?dry_run=true to validate and preview without saving, and an Idempotency-Key header to make retries safe.\nEach API key may make 300 requests per minute, counted in fixed one-minute windows and shared with MCP (each tool call in a batch counts). Authenticated responses carry RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset; over the limit you get 429 with Retry-After. Every response carries an X-Request-Id to quote when asking for help.\nServer-to-server only: the API sends no CORS headers, so browsers cannot call it from other sites."},"servers":[{"url":"https://api.bizisy.com"}],"paths":{"/v1/platform/whoami":{"post":{"operationId":"platform.whoami","summary":"Who am I","description":"Returns the signed-in user, their organization, roles and the audiences (me/manage) they can use, and whether Bizisy billing exists yet (billing). user.language is the language the person chose (null: they follow the company), org.language the company default (null: each browser's language). Call this first to orient yourself.","tags":["platform"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"display_name":{"type":"string"},"language":{"type":"string","nullable":true}},"required":["id","email","display_name","language"],"additionalProperties":false},"org":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"language":{"type":"string","nullable":true}},"required":["id","slug","name","language"],"additionalProperties":false},"roles":{"type":"array","items":{"type":"string"}},"audiences":{"type":"array","items":{"type":"string","enum":["me","manage"]}},"person_id":{"type":"string","nullable":true},"billing":{"type":"boolean","description":"Billing exists (Settings → Billing, platform_billing_* tools); false while billing has not started for anyone, with nothing to set up."},"documents":{"type":"boolean","description":"Documents and file storage exist on this server (documents_* and platform_storage_* tools)."},"paused":{"type":"object","properties":{"reason":{"type":"string","enum":["unpaid","details_missing"]},"since":{"type":"string"},"delete_on":{"type":"string","nullable":true,"description":"Set once Bizisy closed the company for it: the data is deleted on this date unless every overdue invoice is paid (or the details added) before."}},"required":["reason","since","delete_on"],"additionalProperties":false,"nullable":true,"description":"Set while the company is paused for unpaid invoices (or missing billing details): only owners and admins can sign in, in the web app, to pay (Settings → Billing), save a card or export data; every other call is refused until every overdue invoice is paid."}},"required":["user","org","roles","audiences","person_id","billing","documents","paused"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"platform.whoami","summary":"Who am I","description":"Returns the signed-in user, their organization, roles and the audiences (me/manage) they can use, and whether Bizisy billing exists yet (billing). user.language is the language the person chose (null: they follow the company), org.language the company default (null: each browser's language). Call this first to orient yourself.","tags":["platform"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"display_name":{"type":"string"},"language":{"type":"string","nullable":true}},"required":["id","email","display_name","language"],"additionalProperties":false},"org":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"language":{"type":"string","nullable":true}},"required":["id","slug","name","language"],"additionalProperties":false},"roles":{"type":"array","items":{"type":"string"}},"audiences":{"type":"array","items":{"type":"string","enum":["me","manage"]}},"person_id":{"type":"string","nullable":true},"billing":{"type":"boolean","description":"Billing exists (Settings → Billing, platform_billing_* tools); false while billing has not started for anyone, with nothing to set up."},"documents":{"type":"boolean","description":"Documents and file storage exist on this server (documents_* and platform_storage_* tools)."},"paused":{"type":"object","properties":{"reason":{"type":"string","enum":["unpaid","details_missing"]},"since":{"type":"string"},"delete_on":{"type":"string","nullable":true,"description":"Set once Bizisy closed the company for it: the data is deleted on this date unless every overdue invoice is paid (or the details added) before."}},"required":["reason","since","delete_on"],"additionalProperties":false,"nullable":true,"description":"Set while the company is paused for unpaid invoices (or missing billing details): only owners and admins can sign in, in the web app, to pay (Settings → Billing), save a card or export data; every other call is refused until every overdue invoice is paid."}},"required":["user","org","roles","audiences","person_id","billing","documents","paused"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/sign_in_methods.list":{"post":{"operationId":"platform.sign_in_methods.list","summary":"List my sign-in methods","description":"Lists the ways you can sign in to this organization: password, Google and Microsoft, each with linked (connected to your login) and available (offered on the sign-in page: Bizisy offers it and the organization has it on), plus whether your email address is confirmed (email_verified, null when unknown). Google or Microsoft is connected by the person from My profile in the web app.","tags":["platform"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"methods":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["password","google","microsoft"]},"linked":{"type":"boolean"},"available":{"type":"boolean"}},"required":["provider","linked","available"],"additionalProperties":false}},"email_verified":{"type":"boolean","nullable":true}},"required":["methods","email_verified"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"platform.sign_in_methods.list","summary":"List my sign-in methods","description":"Lists the ways you can sign in to this organization: password, Google and Microsoft, each with linked (connected to your login) and available (offered on the sign-in page: Bizisy offers it and the organization has it on), plus whether your email address is confirmed (email_verified, null when unknown). Google or Microsoft is connected by the person from My profile in the web app.","tags":["platform"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"methods":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["password","google","microsoft"]},"linked":{"type":"boolean"},"available":{"type":"boolean"}},"required":["provider","linked","available"],"additionalProperties":false}},"email_verified":{"type":"boolean","nullable":true}},"required":["methods","email_verified"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/api_keys.list":{"post":{"operationId":"platform.api_keys.list","summary":"List my API keys","description":"Lists your own API keys (never the secret).","tags":["platform"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"audience":{"type":"string","enum":["me","manage"]},"last4":{"type":"string"},"created_at":{"type":"string"},"last_used_at":{"type":"string","nullable":true},"revoked":{"type":"boolean"}},"required":["id","name","audience","last4","created_at","last_used_at","revoked"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"platform.api_keys.list","summary":"List my API keys","description":"Lists your own API keys (never the secret).","tags":["platform"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"audience":{"type":"string","enum":["me","manage"]},"last4":{"type":"string"},"created_at":{"type":"string"},"last_used_at":{"type":"string","nullable":true},"revoked":{"type":"boolean"}},"required":["id","name","audience","last4","created_at","last_used_at","revoked"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/api_keys.revoke":{"post":{"operationId":"platform.api_keys.revoke","summary":"Revoke an API key","description":"Revokes one of your API keys immediately. Clients using it lose access.","tags":["platform"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"revoked":{"type":"boolean","enum":[true]}},"required":["id","revoked"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/connections.list":{"post":{"operationId":"platform.connections.list","summary":"List connected apps","description":"Lists the AI apps (MCP clients) connected to Bizisy by signing in: their name, where they come from, Me or Manage, when connected and last used. Your own by default; in Manage, owners and admins may pass everyone=true for the whole company (with who connected each). Tokens are never shown. A connection disconnects on its own after 30 days without use.","tags":["platform"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"everyone":{"type":"boolean","description":"Owners and admins in Manage: the whole company."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"client_name":{"type":"string"},"client_kind":{"type":"string","enum":["cimd","dcr"]},"client_host":{"type":"string","nullable":true,"description":"For apps that publish their identity (e.g. claude.ai): the host it is published on."},"redirect_host":{"type":"string"},"redirect_kind":{"type":"string","enum":["web","local","app"]},"audience":{"type":"string","enum":["me","manage"]},"created_at":{"type":"string"},"last_used_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true,"description":"Disconnects on its own if unused until then (renewed on every use)."},"mine":{"type":"boolean"},"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"}},"required":["id","name","email"],"additionalProperties":false,"nullable":true,"description":"Who connected it (only in the everyone view)."}},"required":["id","client_name","client_kind","client_host","redirect_host","redirect_kind","audience","created_at","last_used_at","expires_at","mine","user"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"platform.connections.list","summary":"List connected apps","description":"Lists the AI apps (MCP clients) connected to Bizisy by signing in: their name, where they come from, Me or Manage, when connected and last used. Your own by default; in Manage, owners and admins may pass everyone=true for the whole company (with who connected each). Tokens are never shown. A connection disconnects on its own after 30 days without use.","tags":["platform"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"client_name":{"type":"string"},"client_kind":{"type":"string","enum":["cimd","dcr"]},"client_host":{"type":"string","nullable":true,"description":"For apps that publish their identity (e.g. claude.ai): the host it is published on."},"redirect_host":{"type":"string"},"redirect_kind":{"type":"string","enum":["web","local","app"]},"audience":{"type":"string","enum":["me","manage"]},"created_at":{"type":"string"},"last_used_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true,"description":"Disconnects on its own if unused until then (renewed on every use)."},"mine":{"type":"boolean"},"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"}},"required":["id","name","email"],"additionalProperties":false,"nullable":true,"description":"Who connected it (only in the everyone view)."}},"required":["id","client_name","client_kind","client_host","redirect_host","redirect_kind","audience","created_at","last_used_at","expires_at","mine","user"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/connections.revoke":{"post":{"operationId":"platform.connections.revoke","summary":"Disconnect an app","description":"Disconnects a connected AI app at once: its tokens stop working and it must ask again to reconnect. Your own connections; owners and admins may disconnect anyone's, but only in the web app (over MCP or an API key, your own only). Take id from platform_connections_list.","tags":["platform"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":64}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"revoked":{"type":"boolean","enum":[true]}},"required":["id","revoked"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/ai.onboarding.status":{"post":{"operationId":"platform.ai.onboarding.status","summary":"AI setup status","description":"For the caller only, in this audience: whether the \"Connect your AI\" journey applies to them (eligible: owners and admins in Manage, everyone in Me) and should show first (show), their own connected apps here with when each first called Bizisy, first made a change and the last tool it used, and the latest change or preview one of their apps made (Activity summary and links). The Bizisy app polls it while someone connects an assistant. Never shows other people's apps or activity.","tags":["platform"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"eligible":{"type":"boolean","description":"Manage: owners and admins. Me: everyone."},"show":{"type":"boolean","description":"The journey is still open for you: eligible, no connected app of your own here yet, not put off."},"redirect":{"type":"boolean","description":"Manage Home opens the journey first: only for a company created since the journey shipped, once per person (until they have seen it), with no connected app and no API key in use."},"state":{"type":"object","properties":{"viewed_at":{"type":"string","nullable":true},"assistant":{"type":"string","enum":["claude","chatgpt","cursor","vscode","gemini","other"],"nullable":true},"skipped_at":{"type":"string","nullable":true}},"required":["viewed_at","assistant","skipped_at"],"additionalProperties":false},"apps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"client_name":{"type":"string"},"assistant":{"type":"string","enum":["claude","chatgpt","cursor","vscode","gemini","other"]},"connected_at":{"type":"string"},"last_used_at":{"type":"string","nullable":true},"first_call_at":{"type":"string","nullable":true,"description":"Its first tool call."},"first_write_at":{"type":"string","nullable":true,"description":"Its first applied change."},"last_tool":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false,"nullable":true},"last_tool_at":{"type":"string","nullable":true}},"required":["id","client_name","assistant","connected_at","last_used_at","first_call_at","first_write_at","last_tool","last_tool_at"],"additionalProperties":false}},"first_call_at":{"type":"string","nullable":true},"first_write_at":{"type":"string","nullable":true},"latest":{"type":"object","properties":{"activity_id":{"type":"string"},"summary":{"type":"string"},"preview":{"type":"boolean","description":"A preview (dry run): nothing was saved."},"app":{"type":"string","nullable":true},"at":{"type":"string"},"links":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"path":{"type":"string"}},"required":["label","path"],"additionalProperties":false}}},"required":["activity_id","summary","preview","app","at","links"],"additionalProperties":false,"nullable":true}},"required":["eligible","show","redirect","state","apps","first_call_at","first_write_at","latest"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"platform.ai.onboarding.status","summary":"AI setup status","description":"For the caller only, in this audience: whether the \"Connect your AI\" journey applies to them (eligible: owners and admins in Manage, everyone in Me) and should show first (show), their own connected apps here with when each first called Bizisy, first made a change and the last tool it used, and the latest change or preview one of their apps made (Activity summary and links). The Bizisy app polls it while someone connects an assistant. Never shows other people's apps or activity.","tags":["platform"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"eligible":{"type":"boolean","description":"Manage: owners and admins. Me: everyone."},"show":{"type":"boolean","description":"The journey is still open for you: eligible, no connected app of your own here yet, not put off."},"redirect":{"type":"boolean","description":"Manage Home opens the journey first: only for a company created since the journey shipped, once per person (until they have seen it), with no connected app and no API key in use."},"state":{"type":"object","properties":{"viewed_at":{"type":"string","nullable":true},"assistant":{"type":"string","enum":["claude","chatgpt","cursor","vscode","gemini","other"],"nullable":true},"skipped_at":{"type":"string","nullable":true}},"required":["viewed_at","assistant","skipped_at"],"additionalProperties":false},"apps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"client_name":{"type":"string"},"assistant":{"type":"string","enum":["claude","chatgpt","cursor","vscode","gemini","other"]},"connected_at":{"type":"string"},"last_used_at":{"type":"string","nullable":true},"first_call_at":{"type":"string","nullable":true,"description":"Its first tool call."},"first_write_at":{"type":"string","nullable":true,"description":"Its first applied change."},"last_tool":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false,"nullable":true},"last_tool_at":{"type":"string","nullable":true}},"required":["id","client_name","assistant","connected_at","last_used_at","first_call_at","first_write_at","last_tool","last_tool_at"],"additionalProperties":false}},"first_call_at":{"type":"string","nullable":true},"first_write_at":{"type":"string","nullable":true},"latest":{"type":"object","properties":{"activity_id":{"type":"string"},"summary":{"type":"string"},"preview":{"type":"boolean","description":"A preview (dry run): nothing was saved."},"app":{"type":"string","nullable":true},"at":{"type":"string"},"links":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"path":{"type":"string"}},"required":["label","path"],"additionalProperties":false}}},"required":["activity_id","summary","preview","app","at","links"],"additionalProperties":false,"nullable":true}},"required":["eligible","show","redirect","state","apps","first_call_at","first_write_at","latest"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/members.list":{"post":{"operationId":"platform.members.list","summary":"List members and roles","description":"Lists everyone who has, or was given, access to this organization: email, name, roles (owner, admin, hr, viewer, member), status, whether they have signed in yet (has_login) and the linked person_id. Read this before changing roles.","tags":["platform"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"membership_id":{"type":"string"},"user_id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","disabled"]},"person_id":{"type":"string","nullable":true},"has_login":{"type":"boolean"}},"required":["membership_id","user_id","email","name","roles","status","person_id","has_login"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"platform.members.list","summary":"List members and roles","description":"Lists everyone who has, or was given, access to this organization: email, name, roles (owner, admin, hr, viewer, member), status, whether they have signed in yet (has_login) and the linked person_id. Read this before changing roles.","tags":["platform"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"membership_id":{"type":"string"},"user_id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","disabled"]},"person_id":{"type":"string","nullable":true},"has_login":{"type":"boolean"}},"required":["membership_id","user_id","email","name","roles","status","person_id","has_login"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/members.set_role":{"post":{"operationId":"platform.members.set_role","summary":"Change a member's role","description":"Sets the single role of a member: owner, admin, hr, viewer or member. Only owners can grant or remove the owner role. The last owner cannot be demoted. Takes effect on their next request.","tags":["platform"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"membership_id":{"type":"string","minLength":1},"role":{"type":"string","enum":["owner","admin","hr","viewer","member"]}},"required":["membership_id","role"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"membership_id":{"type":"string"},"user_id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","disabled"]},"person_id":{"type":"string","nullable":true},"has_login":{"type":"boolean"}},"required":["membership_id","user_id","email","name","roles","status","person_id","has_login"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/members.disable":{"post":{"operationId":"platform.members.disable","summary":"Disable a member's access","description":"Disables a membership: their sessions and API keys stop working immediately. You cannot disable yourself or the last owner; only owners can disable owners.","tags":["platform"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"membership_id":{"type":"string","minLength":1}},"required":["membership_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"membership_id":{"type":"string"},"user_id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","disabled"]},"person_id":{"type":"string","nullable":true},"has_login":{"type":"boolean"}},"required":["membership_id","user_id","email","name","roles","status","person_id","has_login"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/members.link_person":{"post":{"operationId":"platform.members.link_person","summary":"Link a login to a person","description":"Sets which person record a member's login belongs to (person_id), or clears it with person_id null. The link decides whose own profile, team and self-service data that login sees. Use it when someone signed in but their login is not linked to their person (for example after org_setup_init warns about it): take membership_id from platform_members_list and person_id from org_people_list. A person is linked to at most one login, so linking moves the person away from any other login. The person must exist and not be erased. Owners and admins only; only owners can relink an owner's login; nobody can move or clear the link of their own login once it is linked.","tags":["platform"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"membership_id":{"type":"string","minLength":1},"person_id":{"type":"string","minLength":1,"nullable":true}},"required":["membership_id","person_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"membership_id":{"type":"string"},"user_id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","disabled"]},"person_id":{"type":"string","nullable":true},"has_login":{"type":"boolean"}},"required":["membership_id","user_id","email","name","roles","status","person_id","has_login"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/appearance.get":{"post":{"operationId":"platform.appearance.get","summary":"See the organization colours, sidebar style and logo","description":"Returns the colour palette (emerald, violet, indigo, ocean, amber, rose, graphite or terracotta), the sidebar style (ink = dark sidebar, light = light sidebar tinted with the palette), the company logo (logo_url: a path on the company address, null without one) and whether photos and logos can be uploaded on this server (photos_available).","tags":["platform"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"palette":{"type":"string","enum":["emerald","violet","indigo","ocean","amber","rose","graphite","terracotta"]},"shell":{"type":"string","enum":["ink","light"]},"logo_url":{"type":"string","nullable":true},"photos_available":{"type":"boolean"}},"required":["palette","shell","logo_url","photos_available"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"platform.appearance.get","summary":"See the organization colours, sidebar style and logo","description":"Returns the colour palette (emerald, violet, indigo, ocean, amber, rose, graphite or terracotta), the sidebar style (ink = dark sidebar, light = light sidebar tinted with the palette), the company logo (logo_url: a path on the company address, null without one) and whether photos and logos can be uploaded on this server (photos_available).","tags":["platform"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"palette":{"type":"string","enum":["emerald","violet","indigo","ocean","amber","rose","graphite","terracotta"]},"shell":{"type":"string","enum":["ink","light"]},"logo_url":{"type":"string","nullable":true},"photos_available":{"type":"boolean"}},"required":["palette","shell","logo_url","photos_available"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/appearance.set":{"post":{"operationId":"platform.appearance.set","summary":"Change the organization colours and sidebar style","description":"Changes the colour palette and/or the sidebar style used by every page of the organization. Palette: emerald (default), violet, indigo, ocean, amber, rose, graphite, terracotta. Sidebar style: ink (default, dark sidebar) or light (light sidebar tinted with the palette). Send only the fields to change; the other keeps its value. Owners and admins only. The logo has its own actions (platform_appearance_logo_upload / remove).","tags":["platform"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"palette":{"type":"string","enum":["emerald","violet","indigo","ocean","amber","rose","graphite","terracotta"],"description":"Accent colour: emerald (default), violet, indigo, ocean, amber, rose, graphite or terracotta."},"shell":{"type":"string","enum":["ink","light"],"description":"Sidebar style: ink (default, dark sidebar) or light (light sidebar tinted with the palette)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"palette":{"type":"string","enum":["emerald","violet","indigo","ocean","amber","rose","graphite","terracotta"]},"shell":{"type":"string","enum":["ink","light"]},"logo_url":{"type":"string","nullable":true},"photos_available":{"type":"boolean"}},"required":["palette","shell","logo_url","photos_available"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/appearance.logo.upload":{"post":{"operationId":"platform.appearance.logo.upload","summary":"Upload the company logo","description":"Sets the company logo, shown in the sidebar of every page and on the sign-in and invite pages (which anyone who opens the company address can see). The image (image_base64: the file as base64) must be a JPEG, PNG or WebP of at most 2 MB and 24 megapixels (over MCP about 1.5 MB fits; larger files go through the REST API); the server checks the bytes, fits the whole logo on a transparent square, re-encodes it as a 512×512 WebP and drops all metadata. A new upload replaces the old logo. Owners and admins only. Returns logo_url. Use dry_run to check the image without saving it. rate_limited means the server is busy with other images: retry in a few seconds.","tags":["platform"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image_base64":{"type":"string","minLength":1,"maxLength":2900000,"description":"The logo file as base64 (a data: URL is accepted): JPEG, PNG or WebP, at most 2 MB."}},"required":["image_base64"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"logo_url":{"type":"string","nullable":true}},"required":["logo_url"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/appearance.logo.remove":{"post":{"operationId":"platform.appearance.logo.remove","summary":"Remove the company logo","description":"Deletes the company logo; the sidebar and sign-in page show the coloured mark again. Succeeds when there is no logo. Owners and admins only.","tags":["platform"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"logo_url":{"type":"string","nullable":true}},"required":["logo_url"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/sign_in.get":{"post":{"operationId":"platform.sign_in.get","summary":"See which sign-in methods are on","description":"Returns the organization's sign-in methods (methods.password, methods.google, methods.microsoft), each with on (the organization's own choice, enforced on every new sign-in), available (Bizisy offers it at all; password always), linked (how many active members' own logins use it today) and privileged_only (owners and admins who sign in only with it). People can sign in with a method that is on and available. Use linked and privileged_only to tell the user who a change affects. Owners and admins only.","tags":["platform"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"methods":{"type":"object","properties":{"password":{"type":"object","properties":{"on":{"type":"boolean","description":"The organization's own choice: true = turned on here. Enforced on every new sign-in."},"available":{"type":"boolean","description":"Bizisy offers this method at all (password always). People can only use a method that is on AND available."},"linked":{"type":"integer","description":"Active members whose own login uses this method today."},"privileged_only":{"type":"integer","description":"Owners and admins who sign in ONLY with this method (turning it off locks them out)."}},"required":["on","available","linked","privileged_only"],"additionalProperties":false},"google":{"type":"object","properties":{"on":{"type":"boolean","description":"The organization's own choice: true = turned on here. Enforced on every new sign-in."},"available":{"type":"boolean","description":"Bizisy offers this method at all (password always). People can only use a method that is on AND available."},"linked":{"type":"integer","description":"Active members whose own login uses this method today."},"privileged_only":{"type":"integer","description":"Owners and admins who sign in ONLY with this method (turning it off locks them out)."}},"required":["on","available","linked","privileged_only"],"additionalProperties":false},"microsoft":{"type":"object","properties":{"on":{"type":"boolean","description":"The organization's own choice: true = turned on here. Enforced on every new sign-in."},"available":{"type":"boolean","description":"Bizisy offers this method at all (password always). People can only use a method that is on AND available."},"linked":{"type":"integer","description":"Active members whose own login uses this method today."},"privileged_only":{"type":"integer","description":"Owners and admins who sign in ONLY with this method (turning it off locks them out)."}},"required":["on","available","linked","privileged_only"],"additionalProperties":false}},"required":["password","google","microsoft"],"additionalProperties":false}},"required":["methods"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"platform.sign_in.get","summary":"See which sign-in methods are on","description":"Returns the organization's sign-in methods (methods.password, methods.google, methods.microsoft), each with on (the organization's own choice, enforced on every new sign-in), available (Bizisy offers it at all; password always), linked (how many active members' own logins use it today) and privileged_only (owners and admins who sign in only with it). People can sign in with a method that is on and available. Use linked and privileged_only to tell the user who a change affects. Owners and admins only.","tags":["platform"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"methods":{"type":"object","properties":{"password":{"type":"object","properties":{"on":{"type":"boolean","description":"The organization's own choice: true = turned on here. Enforced on every new sign-in."},"available":{"type":"boolean","description":"Bizisy offers this method at all (password always). People can only use a method that is on AND available."},"linked":{"type":"integer","description":"Active members whose own login uses this method today."},"privileged_only":{"type":"integer","description":"Owners and admins who sign in ONLY with this method (turning it off locks them out)."}},"required":["on","available","linked","privileged_only"],"additionalProperties":false},"google":{"type":"object","properties":{"on":{"type":"boolean","description":"The organization's own choice: true = turned on here. Enforced on every new sign-in."},"available":{"type":"boolean","description":"Bizisy offers this method at all (password always). People can only use a method that is on AND available."},"linked":{"type":"integer","description":"Active members whose own login uses this method today."},"privileged_only":{"type":"integer","description":"Owners and admins who sign in ONLY with this method (turning it off locks them out)."}},"required":["on","available","linked","privileged_only"],"additionalProperties":false},"microsoft":{"type":"object","properties":{"on":{"type":"boolean","description":"The organization's own choice: true = turned on here. Enforced on every new sign-in."},"available":{"type":"boolean","description":"Bizisy offers this method at all (password always). People can only use a method that is on AND available."},"linked":{"type":"integer","description":"Active members whose own login uses this method today."},"privileged_only":{"type":"integer","description":"Owners and admins who sign in ONLY with this method (turning it off locks them out)."}},"required":["on","available","linked","privileged_only"],"additionalProperties":false}},"required":["password","google","microsoft"],"additionalProperties":false}},"required":["methods"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/sign_in.set":{"post":{"operationId":"platform.sign_in.set","summary":"Turn sign-in methods on or off","description":"Turns password, Google and Microsoft sign-in on or off for the whole organization. Send only the methods to change, e.g. { \"password\": false }. Rules: at least one method that Bizisy offers must stay on; a method Bizisy does not offer yet (see available in platform_sign_in_get) cannot be turned on; and you cannot lock yourself out by turning off every method your own login uses (connect Google or Microsoft from My profile first). A method Bizisy does not offer can always be turned off. Turning a method off refuses new sign-ins, invite acceptances and password resets with it; people already signed in stay signed in until their session ends (7 days) or they sign out. API keys are a separate credential and keep working whatever is chosen here (revoke them under API keys). Check linked and privileged_only in platform_sign_in_get to tell the user who is affected, and preview with dry_run first. Owners and admins only.","tags":["platform"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"boolean","description":"Email and password sign-in: true turns it on, false turns it off."},"google":{"type":"boolean","description":"Continue with Google: true turns it on, false turns it off. Only when available on Bizisy."},"microsoft":{"type":"boolean","description":"Continue with Microsoft: true turns it on, false turns it off. Only when available on Bizisy."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"methods":{"type":"object","properties":{"password":{"type":"object","properties":{"on":{"type":"boolean","description":"The organization's own choice: true = turned on here. Enforced on every new sign-in."},"available":{"type":"boolean","description":"Bizisy offers this method at all (password always). People can only use a method that is on AND available."},"linked":{"type":"integer","description":"Active members whose own login uses this method today."},"privileged_only":{"type":"integer","description":"Owners and admins who sign in ONLY with this method (turning it off locks them out)."}},"required":["on","available","linked","privileged_only"],"additionalProperties":false},"google":{"type":"object","properties":{"on":{"type":"boolean","description":"The organization's own choice: true = turned on here. Enforced on every new sign-in."},"available":{"type":"boolean","description":"Bizisy offers this method at all (password always). People can only use a method that is on AND available."},"linked":{"type":"integer","description":"Active members whose own login uses this method today."},"privileged_only":{"type":"integer","description":"Owners and admins who sign in ONLY with this method (turning it off locks them out)."}},"required":["on","available","linked","privileged_only"],"additionalProperties":false},"microsoft":{"type":"object","properties":{"on":{"type":"boolean","description":"The organization's own choice: true = turned on here. Enforced on every new sign-in."},"available":{"type":"boolean","description":"Bizisy offers this method at all (password always). People can only use a method that is on AND available."},"linked":{"type":"integer","description":"Active members whose own login uses this method today."},"privileged_only":{"type":"integer","description":"Owners and admins who sign in ONLY with this method (turning it off locks them out)."}},"required":["on","available","linked","privileged_only"],"additionalProperties":false}},"required":["password","google","microsoft"],"additionalProperties":false}},"required":["methods"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/activity.list":{"post":{"operationId":"platform.activity.list","summary":"List activity","description":"Lists Activity entries, newest first: every change made in Bizisy (and, for AI assistants, every preview and failed attempt), with who did it, through what (web or which API key), status (ok, dry_run = preview only, error), a one-line summary and links to what it touched. Owners, admins and HR (in Manage) see the whole organization; everyone else, and every call through the me audience, sees only their own activity. Filter by status, channel (ui, api, mcp, job), action_id, actor_user_id, or subject_id: entries about one record, e.g. a person id from org_people_list (changes to their profile, job, pay, invites and login link). Each entry lists subject_ids (ids only, never names). Page with before = next_before from the previous page; limit defaults to 50 (at most 100).","tags":["platform"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","dry_run","error"]},"actor_user_id":{"type":"string","minLength":1},"action_id":{"type":"string","minLength":1},"channel":{"type":"string","enum":["ui","api","mcp","job"]},"subject_id":{"type":"string","minLength":1,"description":"A record id (e.g. a person id): only entries about it."},"before":{"type":"string","minLength":1,"nullable":true,"description":"An entry id: return only entries older than it (next_before of the previous page)."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"action_id":{"type":"string"},"action_title":{"type":"string"},"kind":{"type":"string","enum":["read","write","destructive"]},"channel":{"type":"string","enum":["ui","api","mcp","job"]},"status":{"type":"string","enum":["ok","dry_run","error"]},"dry_run":{"type":"boolean"},"summary":{"type":"string"},"actor":{"type":"object","properties":{"user_id":{"type":"string"},"person_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"credential":{"type":"object","properties":{"kind":{"type":"string","enum":["session","api_key"]},"id":{"type":"string"},"name":{"type":"string","nullable":true},"app":{"type":"boolean","description":"A connected app (signed in with OAuth) rather than an API key; name is the app's."}},"required":["kind","id","name","app"],"additionalProperties":false}},"required":["user_id","person_id","name","email","credential"],"additionalProperties":false,"nullable":true},"input":{"type":"object","additionalProperties":{},"nullable":true},"input_keys":{"type":"array","items":{"type":"string"},"nullable":true},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false,"nullable":true},"links":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"path":{"type":"string"}},"required":["label","path"],"additionalProperties":false}},"subject_ids":{"type":"array","items":{"type":"string"}},"events":{"type":"array","items":{"type":"string"}}},"required":["id","created_at","action_id","action_title","kind","channel","status","dry_run","summary","actor","input","input_keys","error","links","subject_ids","events"],"additionalProperties":false}},"next_before":{"type":"string","nullable":true}},"required":["entries","next_before"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"platform.activity.list","summary":"List activity","description":"Lists Activity entries, newest first: every change made in Bizisy (and, for AI assistants, every preview and failed attempt), with who did it, through what (web or which API key), status (ok, dry_run = preview only, error), a one-line summary and links to what it touched. Owners, admins and HR (in Manage) see the whole organization; everyone else, and every call through the me audience, sees only their own activity. Filter by status, channel (ui, api, mcp, job), action_id, actor_user_id, or subject_id: entries about one record, e.g. a person id from org_people_list (changes to their profile, job, pay, invites and login link). Each entry lists subject_ids (ids only, never names). Page with before = next_before from the previous page; limit defaults to 50 (at most 100).","tags":["platform"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"action_id":{"type":"string"},"action_title":{"type":"string"},"kind":{"type":"string","enum":["read","write","destructive"]},"channel":{"type":"string","enum":["ui","api","mcp","job"]},"status":{"type":"string","enum":["ok","dry_run","error"]},"dry_run":{"type":"boolean"},"summary":{"type":"string"},"actor":{"type":"object","properties":{"user_id":{"type":"string"},"person_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"credential":{"type":"object","properties":{"kind":{"type":"string","enum":["session","api_key"]},"id":{"type":"string"},"name":{"type":"string","nullable":true},"app":{"type":"boolean","description":"A connected app (signed in with OAuth) rather than an API key; name is the app's."}},"required":["kind","id","name","app"],"additionalProperties":false}},"required":["user_id","person_id","name","email","credential"],"additionalProperties":false,"nullable":true},"input":{"type":"object","additionalProperties":{},"nullable":true},"input_keys":{"type":"array","items":{"type":"string"},"nullable":true},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false,"nullable":true},"links":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"path":{"type":"string"}},"required":["label","path"],"additionalProperties":false}},"subject_ids":{"type":"array","items":{"type":"string"}},"events":{"type":"array","items":{"type":"string"}}},"required":["id","created_at","action_id","action_title","kind","channel","status","dry_run","summary","actor","input","input_keys","error","links","subject_ids","events"],"additionalProperties":false}},"next_before":{"type":"string","nullable":true}},"required":["entries","next_before"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/activity.get":{"post":{"operationId":"platform.activity.get","summary":"Get an activity entry","description":"Returns one Activity entry by id (the id at the end of a view_url). Owners, admins and HR (in Manage) see the whole organization; everyone else, and every call through the me audience, sees only their own activity. not_found otherwise.","tags":["platform"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"action_id":{"type":"string"},"action_title":{"type":"string"},"kind":{"type":"string","enum":["read","write","destructive"]},"channel":{"type":"string","enum":["ui","api","mcp","job"]},"status":{"type":"string","enum":["ok","dry_run","error"]},"dry_run":{"type":"boolean"},"summary":{"type":"string"},"actor":{"type":"object","properties":{"user_id":{"type":"string"},"person_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"credential":{"type":"object","properties":{"kind":{"type":"string","enum":["session","api_key"]},"id":{"type":"string"},"name":{"type":"string","nullable":true},"app":{"type":"boolean","description":"A connected app (signed in with OAuth) rather than an API key; name is the app's."}},"required":["kind","id","name","app"],"additionalProperties":false}},"required":["user_id","person_id","name","email","credential"],"additionalProperties":false,"nullable":true},"input":{"type":"object","additionalProperties":{},"nullable":true},"input_keys":{"type":"array","items":{"type":"string"},"nullable":true},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false,"nullable":true},"links":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"path":{"type":"string"}},"required":["label","path"],"additionalProperties":false}},"subject_ids":{"type":"array","items":{"type":"string"}},"events":{"type":"array","items":{"type":"string"}}},"required":["id","created_at","action_id","action_title","kind","channel","status","dry_run","summary","actor","input","input_keys","error","links","subject_ids","events"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"platform.activity.get","summary":"Get an activity entry","description":"Returns one Activity entry by id (the id at the end of a view_url). Owners, admins and HR (in Manage) see the whole organization; everyone else, and every call through the me audience, sees only their own activity. not_found otherwise.","tags":["platform"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"action_id":{"type":"string"},"action_title":{"type":"string"},"kind":{"type":"string","enum":["read","write","destructive"]},"channel":{"type":"string","enum":["ui","api","mcp","job"]},"status":{"type":"string","enum":["ok","dry_run","error"]},"dry_run":{"type":"boolean"},"summary":{"type":"string"},"actor":{"type":"object","properties":{"user_id":{"type":"string"},"person_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"credential":{"type":"object","properties":{"kind":{"type":"string","enum":["session","api_key"]},"id":{"type":"string"},"name":{"type":"string","nullable":true},"app":{"type":"boolean","description":"A connected app (signed in with OAuth) rather than an API key; name is the app's."}},"required":["kind","id","name","app"],"additionalProperties":false}},"required":["user_id","person_id","name","email","credential"],"additionalProperties":false,"nullable":true},"input":{"type":"object","additionalProperties":{},"nullable":true},"input_keys":{"type":"array","items":{"type":"string"},"nullable":true},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false,"nullable":true},"links":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"path":{"type":"string"}},"required":["label","path"],"additionalProperties":false}},"subject_ids":{"type":"array","items":{"type":"string"}},"events":{"type":"array","items":{"type":"string"}}},"required":["id","created_at","action_id","action_title","kind","channel","status","dry_run","summary","actor","input","input_keys","error","links","subject_ids","events"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/language.set_mine":{"post":{"operationId":"platform.language.set_mine","summary":"Change my language","description":"Sets the language Bizisy uses for you: the web app (Me and Manage, on every device and in every company you belong to) and the emails you receive. Languages: en (English), pt-PT (Português), es-ES (Español), de-DE (Deutsch), fr-FR (Français), it-IT (Italiano). null = follow the company default (or, without one, the browser's language). Any signed-in person, for themselves only. platform_whoami returns the current choice (user.language) and the company default (org.language).","tags":["platform"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string","enum":["en","pt-PT","es-ES","de-DE","fr-FR","it-IT"],"nullable":true,"description":"One of en, pt-PT, es-ES, de-DE, fr-FR, it-IT, or null to follow the company default."}},"required":["language"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"language":{"type":"string","enum":["en","pt-PT","es-ES","de-DE","fr-FR","it-IT"],"nullable":true}},"required":["language"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/language.set_company":{"post":{"operationId":"platform.language.set_company","summary":"Change the company language","description":"Sets the company's default language: used by everyone who has not chosen their own language (in Me → My profile) and for the company's emails to them. Languages: en (English), pt-PT (Português), es-ES (Español), de-DE (Deutsch), fr-FR (Français), it-IT (Italiano). null = automatic: each person's browser language. People who chose a language keep it. Owners and admins only.","tags":["platform"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string","enum":["en","pt-PT","es-ES","de-DE","fr-FR","it-IT"],"nullable":true,"description":"One of en, pt-PT, es-ES, de-DE, fr-FR, it-IT, or null for automatic (the browser's language)."}},"required":["language"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"language":{"type":"string","enum":["en","pt-PT","es-ES","de-DE","fr-FR","it-IT"],"nullable":true}},"required":["language"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/org.status":{"post":{"operationId":"platform.org.status","summary":"Company account status","description":"Whether the company account is active or closing (closed, with its data deleted on delete_after unless an owner reopens it), and whether you may close it (can_close: an owner in the web app). Closing, reopening and the full company export happen only in the web app: send the user to Manage → Settings → Close account.","tags":["platform"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["active","closing"]},"closed_at":{"type":"string","nullable":true},"delete_after":{"type":"string","nullable":true},"can_close":{"type":"boolean","description":"The caller may close the company: an owner signed in to the web app."}},"required":["status","closed_at","delete_after","can_close"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"platform.org.status","summary":"Company account status","description":"Whether the company account is active or closing (closed, with its data deleted on delete_after unless an owner reopens it), and whether you may close it (can_close: an owner in the web app). Closing, reopening and the full company export happen only in the web app: send the user to Manage → Settings → Close account.","tags":["platform"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["active","closing"]},"closed_at":{"type":"string","nullable":true},"delete_after":{"type":"string","nullable":true},"can_close":{"type":"boolean","description":"The caller may close the company: an owner signed in to the web app."}},"required":["status","closed_at","delete_after","can_close"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/notifications.list":{"post":{"operationId":"platform.notifications.list","summary":"List my notifications","description":"Your Bizisy notifications, newest first: reminders (probation and fixed-term contracts ending, people starting, work anniversaries), checklist tasks due, changes waiting for your approval, and documents people added. You get the same ones you would get by email, whether or not your company emails them; each has an href to open it in Bizisy. Each is checked against what you may see now: one that no longer applies (the request was decided, the task done, the document deleted, or you no longer hold the role that earned it) disappears; one that cannot be checked right now comes back as kind unavailable. Over an API key or AI app, pay change requests are never listed. Kept 90 days. limit 1–50 (default 20; 0 returns only the unread count); before = the next value of the previous page; unread_only. Only your own notifications.","tags":["platform"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","minimum":0,"maximum":50,"default":20},"before":{"type":"string","maxLength":200},"unread_only":{"type":"boolean","default":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["reminder","task","approval_request","document_uploaded","unavailable"],"description":"reminder (probation or contract ending, someone starting, a work anniversary), task (a checklist task due), approval_request (a change waits for your decision), document_uploaded (someone added a document of their own), or unavailable (it could not be loaded just now: try again later; nothing else is known)."},"created_at":{"type":"string"},"read":{"type":"boolean"},"href":{"type":"string","nullable":true,"description":"Where it leads, on the company address: /manage/… opens Manage, any other path My workspace. null when unavailable."},"person_name":{"type":"string","nullable":true,"description":"Who it is about; null when unavailable."},"date":{"type":"string","nullable":true,"description":"YYYY-MM-DD: the reminder date, the task due date or the date the change takes effect."},"reminder":{"type":"object","properties":{"kind":{"type":"string","enum":["probation_end","contract_end","start_soon","start_today","anniversary"]},"years":{"type":"integer","nullable":true,"description":"Anniversaries: years of service."},"self":{"type":"boolean","description":"The reminder is about the reader (their own anniversary)."}},"required":["kind","years","self"],"additionalProperties":false,"nullable":true},"task":{"type":"object","properties":{"title":{"type":"string"},"checklist":{"type":"string"},"own":{"type":"boolean","description":"The task is in the reader's own checklist."}},"required":["title","checklist","own"],"additionalProperties":false,"nullable":true},"approval":{"type":"object","properties":{"change":{"type":"string","enum":["job_change","termination","pay_change"],"description":"The kind of change (never a pay amount)."},"proposer_name":{"type":"string"},"as":{"type":"string","enum":["manager","hr","lead"],"description":"Why the reader decides: as the person's manager, as HR, or as the lead of their team (when they have no manager)."}},"required":["change","proposer_name","as"],"additionalProperties":false,"nullable":true},"document":{"type":"object","properties":{"category":{"type":"string"}},"required":["category"],"additionalProperties":false,"nullable":true}},"required":["id","kind","created_at","read","href","person_name","date","reminder","task","approval","document"],"additionalProperties":false}},"unread":{"type":"integer","description":"Unread notifications in total."},"next":{"type":"string","nullable":true,"description":"Pass as before for the next page; null at the end."}},"required":["items","unread","next"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"platform.notifications.list","summary":"List my notifications","description":"Your Bizisy notifications, newest first: reminders (probation and fixed-term contracts ending, people starting, work anniversaries), checklist tasks due, changes waiting for your approval, and documents people added. You get the same ones you would get by email, whether or not your company emails them; each has an href to open it in Bizisy. Each is checked against what you may see now: one that no longer applies (the request was decided, the task done, the document deleted, or you no longer hold the role that earned it) disappears; one that cannot be checked right now comes back as kind unavailable. Over an API key or AI app, pay change requests are never listed. Kept 90 days. limit 1–50 (default 20; 0 returns only the unread count); before = the next value of the previous page; unread_only. Only your own notifications.","tags":["platform"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["reminder","task","approval_request","document_uploaded","unavailable"],"description":"reminder (probation or contract ending, someone starting, a work anniversary), task (a checklist task due), approval_request (a change waits for your decision), document_uploaded (someone added a document of their own), or unavailable (it could not be loaded just now: try again later; nothing else is known)."},"created_at":{"type":"string"},"read":{"type":"boolean"},"href":{"type":"string","nullable":true,"description":"Where it leads, on the company address: /manage/… opens Manage, any other path My workspace. null when unavailable."},"person_name":{"type":"string","nullable":true,"description":"Who it is about; null when unavailable."},"date":{"type":"string","nullable":true,"description":"YYYY-MM-DD: the reminder date, the task due date or the date the change takes effect."},"reminder":{"type":"object","properties":{"kind":{"type":"string","enum":["probation_end","contract_end","start_soon","start_today","anniversary"]},"years":{"type":"integer","nullable":true,"description":"Anniversaries: years of service."},"self":{"type":"boolean","description":"The reminder is about the reader (their own anniversary)."}},"required":["kind","years","self"],"additionalProperties":false,"nullable":true},"task":{"type":"object","properties":{"title":{"type":"string"},"checklist":{"type":"string"},"own":{"type":"boolean","description":"The task is in the reader's own checklist."}},"required":["title","checklist","own"],"additionalProperties":false,"nullable":true},"approval":{"type":"object","properties":{"change":{"type":"string","enum":["job_change","termination","pay_change"],"description":"The kind of change (never a pay amount)."},"proposer_name":{"type":"string"},"as":{"type":"string","enum":["manager","hr","lead"],"description":"Why the reader decides: as the person's manager, as HR, or as the lead of their team (when they have no manager)."}},"required":["change","proposer_name","as"],"additionalProperties":false,"nullable":true},"document":{"type":"object","properties":{"category":{"type":"string"}},"required":["category"],"additionalProperties":false,"nullable":true}},"required":["id","kind","created_at","read","href","person_name","date","reminder","task","approval","document"],"additionalProperties":false}},"unread":{"type":"integer","description":"Unread notifications in total."},"next":{"type":"string","nullable":true,"description":"Pass as before for the next page; null at the end."}},"required":["items","unread","next"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/notifications.mark_read":{"post":{"operationId":"platform.notifications.mark_read","summary":"Mark notifications as read","description":"Marks some of your own notifications as read (ids from platform_notifications_list, 1–100). Ids that are not yours or already read are ignored: marked says how many changed. Not recorded in Activity (your own inbox only).","tags":["platform"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":100}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"marked":{"type":"integer"},"unread":{"type":"integer"}},"required":["marked","unread"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/notifications.mark_all_read":{"post":{"operationId":"platform.notifications.mark_all_read","summary":"Mark all notifications as read","description":"Marks every one of your own unread notifications as read (over an API key or AI app, those it can list). Not recorded in Activity (your own inbox only).","tags":["platform"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"marked":{"type":"integer"},"unread":{"type":"integer"}},"required":["marked","unread"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/notifications.settings.get":{"post":{"operationId":"platform.notifications.settings.get","summary":"See notification settings","description":"Returns which optional emails the company sends, its monthly limit on extra emails, and this month's usage (sent, held by the limit, shown in the app because their email is off, the allowance, extra, blocks billed and the estimate). Owners and admins. Every optional notice (daily reminders and checklist tasks, approval requests, documents people added) always appears in the recipients' Bizisy notifications; this decides which are also emailed (email: { reminders, approval_request, document_uploaded }, all on by default) and an optional monthly limit on extra emails (extra_limit). 10 optional emails per active person per month are included, pooled across the company; above that they cost €1 per 1,000 (€0.10 per block of 100, rounded up), excluding VAT, billed with the monthly invoice once billing has started (included before, and in the uncharged first month). Sign-in, invite, security, billing and closure emails are always sent and never counted.","tags":["platform"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"email":{"type":"object","properties":{"reminders":{"type":"boolean","description":"The daily reminders email (probation and contracts ending, starters, anniversaries, and checklist tasks due): one digest per person per day."},"approval_request":{"type":"boolean","description":"An email to each approver when a change waits for their decision."},"document_uploaded":{"type":"boolean","description":"An email to owners, admins and HR when someone adds a document of their own."}},"required":["reminders","approval_request","document_uploaded"],"additionalProperties":false,"description":"Per optional type: true = emailed and in the app; false = in the app only."},"extra_limit":{"type":"integer","nullable":true,"description":"At most this many optional emails a month above the included allowance; once reached, notices stay in the app only until next month. null = no limit."},"usage":{"type":"object","properties":{"month":{"type":"string","description":"The current month (YYYY-MM, UTC: billing months run 1st to 1st)."},"sent":{"type":"integer","description":"Optional emails sent this month (a daily digest counts as one)."},"held":{"type":"integer","description":"Optional emails not sent this month because the limit was reached (they are in the app)."},"in_app_only":{"type":"integer","description":"Optional notices not emailed this month because their email is off."},"active_people":{"type":"integer"},"allowance":{"type":"integer","description":"Included this month: 10 per active person, pooled."},"extra":{"type":"integer","description":"Sent above the allowance."},"billable_units":{"type":"integer","description":"Blocks of 100 emails above the allowance (rounded up), never more than the monthly limit allows."},"unit_size":{"type":"integer"},"unit_price_cents":{"type":"integer","description":"€0.10 per block of 100, excluding VAT (= €1 per 1,000 emails)."},"estimated_cents":{"type":"integer","description":"This month's optional emails so far, excluding VAT; billed with the monthly invoice."}},"required":["month","sent","held","in_app_only","active_people","allowance","extra","billable_units","unit_size","unit_price_cents","estimated_cents"],"additionalProperties":false},"billed":{"type":"boolean","description":"Emails above the allowance are charged now (a paid subscription runs and the email price applies); false before billing starts, during the uncharged first month and until billing_from: they are included."},"billing_from":{"type":"string","nullable":true,"description":"YYYY-MM-DD (a 1st): from when emails above the allowance are charged, at least 30 days after the company was told the price; null until it was told (nothing is charged)."}},"required":["email","extra_limit","usage","billed","billing_from"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"platform.notifications.settings.get","summary":"See notification settings","description":"Returns which optional emails the company sends, its monthly limit on extra emails, and this month's usage (sent, held by the limit, shown in the app because their email is off, the allowance, extra, blocks billed and the estimate). Owners and admins. Every optional notice (daily reminders and checklist tasks, approval requests, documents people added) always appears in the recipients' Bizisy notifications; this decides which are also emailed (email: { reminders, approval_request, document_uploaded }, all on by default) and an optional monthly limit on extra emails (extra_limit). 10 optional emails per active person per month are included, pooled across the company; above that they cost €1 per 1,000 (€0.10 per block of 100, rounded up), excluding VAT, billed with the monthly invoice once billing has started (included before, and in the uncharged first month). Sign-in, invite, security, billing and closure emails are always sent and never counted.","tags":["platform"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"email":{"type":"object","properties":{"reminders":{"type":"boolean","description":"The daily reminders email (probation and contracts ending, starters, anniversaries, and checklist tasks due): one digest per person per day."},"approval_request":{"type":"boolean","description":"An email to each approver when a change waits for their decision."},"document_uploaded":{"type":"boolean","description":"An email to owners, admins and HR when someone adds a document of their own."}},"required":["reminders","approval_request","document_uploaded"],"additionalProperties":false,"description":"Per optional type: true = emailed and in the app; false = in the app only."},"extra_limit":{"type":"integer","nullable":true,"description":"At most this many optional emails a month above the included allowance; once reached, notices stay in the app only until next month. null = no limit."},"usage":{"type":"object","properties":{"month":{"type":"string","description":"The current month (YYYY-MM, UTC: billing months run 1st to 1st)."},"sent":{"type":"integer","description":"Optional emails sent this month (a daily digest counts as one)."},"held":{"type":"integer","description":"Optional emails not sent this month because the limit was reached (they are in the app)."},"in_app_only":{"type":"integer","description":"Optional notices not emailed this month because their email is off."},"active_people":{"type":"integer"},"allowance":{"type":"integer","description":"Included this month: 10 per active person, pooled."},"extra":{"type":"integer","description":"Sent above the allowance."},"billable_units":{"type":"integer","description":"Blocks of 100 emails above the allowance (rounded up), never more than the monthly limit allows."},"unit_size":{"type":"integer"},"unit_price_cents":{"type":"integer","description":"€0.10 per block of 100, excluding VAT (= €1 per 1,000 emails)."},"estimated_cents":{"type":"integer","description":"This month's optional emails so far, excluding VAT; billed with the monthly invoice."}},"required":["month","sent","held","in_app_only","active_people","allowance","extra","billable_units","unit_size","unit_price_cents","estimated_cents"],"additionalProperties":false},"billed":{"type":"boolean","description":"Emails above the allowance are charged now (a paid subscription runs and the email price applies); false before billing starts, during the uncharged first month and until billing_from: they are included."},"billing_from":{"type":"string","nullable":true,"description":"YYYY-MM-DD (a 1st): from when emails above the allowance are charged, at least 30 days after the company was told the price; null until it was told (nothing is charged)."}},"required":["email","extra_limit","usage","billed","billing_from"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/notifications.settings.update":{"post":{"operationId":"platform.notifications.settings.update","summary":"Change notification settings","description":"Changes which optional emails the company sends and the monthly limit on extra emails. Send only what changes: email (any of reminders, approval_request, document_uploaded: true or false) and/or extra_limit (0–100000, or null for no limit). Turning an email off keeps the notices in the app. Preview with dry_run. Owners and admins. Every optional notice (daily reminders and checklist tasks, approval requests, documents people added) always appears in the recipients' Bizisy notifications; this decides which are also emailed (email: { reminders, approval_request, document_uploaded }, all on by default) and an optional monthly limit on extra emails (extra_limit). 10 optional emails per active person per month are included, pooled across the company; above that they cost €1 per 1,000 (€0.10 per block of 100, rounded up), excluding VAT, billed with the monthly invoice once billing has started (included before, and in the uncharged first month). Sign-in, invite, security, billing and closure emails are always sent and never counted.","tags":["platform"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"object","properties":{"reminders":{"type":"boolean"},"approval_request":{"type":"boolean"},"document_uploaded":{"type":"boolean"}},"additionalProperties":false},"extra_limit":{"type":"integer","minimum":0,"maximum":100000,"nullable":true}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"email":{"type":"object","properties":{"reminders":{"type":"boolean","description":"The daily reminders email (probation and contracts ending, starters, anniversaries, and checklist tasks due): one digest per person per day."},"approval_request":{"type":"boolean","description":"An email to each approver when a change waits for their decision."},"document_uploaded":{"type":"boolean","description":"An email to owners, admins and HR when someone adds a document of their own."}},"required":["reminders","approval_request","document_uploaded"],"additionalProperties":false,"description":"Per optional type: true = emailed and in the app; false = in the app only."},"extra_limit":{"type":"integer","nullable":true,"description":"At most this many optional emails a month above the included allowance; once reached, notices stay in the app only until next month. null = no limit."},"usage":{"type":"object","properties":{"month":{"type":"string","description":"The current month (YYYY-MM, UTC: billing months run 1st to 1st)."},"sent":{"type":"integer","description":"Optional emails sent this month (a daily digest counts as one)."},"held":{"type":"integer","description":"Optional emails not sent this month because the limit was reached (they are in the app)."},"in_app_only":{"type":"integer","description":"Optional notices not emailed this month because their email is off."},"active_people":{"type":"integer"},"allowance":{"type":"integer","description":"Included this month: 10 per active person, pooled."},"extra":{"type":"integer","description":"Sent above the allowance."},"billable_units":{"type":"integer","description":"Blocks of 100 emails above the allowance (rounded up), never more than the monthly limit allows."},"unit_size":{"type":"integer"},"unit_price_cents":{"type":"integer","description":"€0.10 per block of 100, excluding VAT (= €1 per 1,000 emails)."},"estimated_cents":{"type":"integer","description":"This month's optional emails so far, excluding VAT; billed with the monthly invoice."}},"required":["month","sent","held","in_app_only","active_people","allowance","extra","billable_units","unit_size","unit_price_cents","estimated_cents"],"additionalProperties":false},"billed":{"type":"boolean","description":"Emails above the allowance are charged now (a paid subscription runs and the email price applies); false before billing starts, during the uncharged first month and until billing_from: they are included."},"billing_from":{"type":"string","nullable":true,"description":"YYYY-MM-DD (a 1st): from when emails above the allowance are charged, at least 30 days after the company was told the price; null until it was told (nothing is charged)."},"changed":{"type":"array","items":{"type":"string"},"description":"What changed, e.g. email.reminders, extra_limit."}},"required":["email","extra_limit","usage","billed","billing_from","changed"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/storage.get":{"post":{"operationId":"platform.storage.get","summary":"See storage","description":"Returns the company's storage: bytes stored now (documents, profile photos and the logo), the highest size this month (what storage is billed on), what is included (500 MB), the price above it (€0.10 per 0.1 GB per month, i.e. €1 per GB, excluding VAT, billed with the monthly invoice on the month's highest size), this month's estimate, and the limits (largest file, company ceiling, self uploads per person per month). Owners, admins and HR.","tags":["platform"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"bytes":{"type":"integer","description":"Bytes stored now: documents, profile photos and the company logo."},"files":{"type":"integer"},"month":{"type":"string","description":"The current billing month (YYYY-MM, UTC)."},"peak_bytes":{"type":"integer","description":"The highest size reached this month: what the month is billed on (deleting files does not lower it)."},"free_bytes":{"type":"integer","description":"Included in the price: 500 MB (decimal: 1 GB = 1000 MB)."},"unit_bytes":{"type":"integer","description":"One billing unit: 0.1 GB (100 MB)."},"unit_price_cents":{"type":"integer","description":"€0.10 per unit per month, excluding VAT (= €1 per GB)."},"billable_units":{"type":"integer","description":"ceil(max(0, peak − 500 MB) / 100 MB) for this month so far."},"estimated_cents":{"type":"integer","description":"billable_units × unit price, excluding VAT, for this month so far."},"billed":{"type":"boolean","description":"Storage is charged for this company (billing exists and has started); false before billing has started."},"limits":{"type":"object","properties":{"max_file_mb":{"type":"integer","minimum":1,"maximum":100,"description":"Largest file, in MB (1–100; default 25)."},"ceiling_gb":{"type":"integer","minimum":1,"maximum":200,"description":"Company storage ceiling, in GB (1–200; at most 10 until paid billing is running; default 10)."},"self_files_per_month":{"type":"integer","minimum":0,"maximum":200,"description":"Files each person may add to \"From me\" per month (0–200; 0 turns self upload off; default 20)."},"self_mb_per_month":{"type":"integer","minimum":0,"maximum":1000,"description":"MB each person may add to \"From me\" per month (0–1000; 0 turns self upload off; default 100)."}},"required":["max_file_mb","ceiling_gb","self_files_per_month","self_mb_per_month"],"additionalProperties":false},"defaults":{"type":"object","properties":{"max_file_mb":{"type":"integer","minimum":1,"maximum":100,"description":"Largest file, in MB (1–100; default 25)."},"ceiling_gb":{"type":"integer","minimum":1,"maximum":200,"description":"Company storage ceiling, in GB (1–200; at most 10 until paid billing is running; default 10)."},"self_files_per_month":{"type":"integer","minimum":0,"maximum":200,"description":"Files each person may add to \"From me\" per month (0–200; 0 turns self upload off; default 20)."},"self_mb_per_month":{"type":"integer","minimum":0,"maximum":1000,"description":"MB each person may add to \"From me\" per month (0–1000; 0 turns self upload off; default 100)."}},"required":["max_file_mb","ceiling_gb","self_files_per_month","self_mb_per_month"],"additionalProperties":false},"ceiling_max_gb":{"type":"integer","description":"The highest ceiling this company may set now."},"by_module":{"type":"array","items":{"type":"object","properties":{"module":{"type":"string"},"bytes":{"type":"integer"},"files":{"type":"integer"}},"required":["module","bytes","files"],"additionalProperties":false},"description":"documents = documents; org = profile photos; platform = the company logo."}},"required":["bytes","files","month","peak_bytes","free_bytes","unit_bytes","unit_price_cents","billable_units","estimated_cents","billed","limits","defaults","ceiling_max_gb","by_module"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"platform.storage.get","summary":"See storage","description":"Returns the company's storage: bytes stored now (documents, profile photos and the logo), the highest size this month (what storage is billed on), what is included (500 MB), the price above it (€0.10 per 0.1 GB per month, i.e. €1 per GB, excluding VAT, billed with the monthly invoice on the month's highest size), this month's estimate, and the limits (largest file, company ceiling, self uploads per person per month). Owners, admins and HR.","tags":["platform"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"bytes":{"type":"integer","description":"Bytes stored now: documents, profile photos and the company logo."},"files":{"type":"integer"},"month":{"type":"string","description":"The current billing month (YYYY-MM, UTC)."},"peak_bytes":{"type":"integer","description":"The highest size reached this month: what the month is billed on (deleting files does not lower it)."},"free_bytes":{"type":"integer","description":"Included in the price: 500 MB (decimal: 1 GB = 1000 MB)."},"unit_bytes":{"type":"integer","description":"One billing unit: 0.1 GB (100 MB)."},"unit_price_cents":{"type":"integer","description":"€0.10 per unit per month, excluding VAT (= €1 per GB)."},"billable_units":{"type":"integer","description":"ceil(max(0, peak − 500 MB) / 100 MB) for this month so far."},"estimated_cents":{"type":"integer","description":"billable_units × unit price, excluding VAT, for this month so far."},"billed":{"type":"boolean","description":"Storage is charged for this company (billing exists and has started); false before billing has started."},"limits":{"type":"object","properties":{"max_file_mb":{"type":"integer","minimum":1,"maximum":100,"description":"Largest file, in MB (1–100; default 25)."},"ceiling_gb":{"type":"integer","minimum":1,"maximum":200,"description":"Company storage ceiling, in GB (1–200; at most 10 until paid billing is running; default 10)."},"self_files_per_month":{"type":"integer","minimum":0,"maximum":200,"description":"Files each person may add to \"From me\" per month (0–200; 0 turns self upload off; default 20)."},"self_mb_per_month":{"type":"integer","minimum":0,"maximum":1000,"description":"MB each person may add to \"From me\" per month (0–1000; 0 turns self upload off; default 100)."}},"required":["max_file_mb","ceiling_gb","self_files_per_month","self_mb_per_month"],"additionalProperties":false},"defaults":{"type":"object","properties":{"max_file_mb":{"type":"integer","minimum":1,"maximum":100,"description":"Largest file, in MB (1–100; default 25)."},"ceiling_gb":{"type":"integer","minimum":1,"maximum":200,"description":"Company storage ceiling, in GB (1–200; at most 10 until paid billing is running; default 10)."},"self_files_per_month":{"type":"integer","minimum":0,"maximum":200,"description":"Files each person may add to \"From me\" per month (0–200; 0 turns self upload off; default 20)."},"self_mb_per_month":{"type":"integer","minimum":0,"maximum":1000,"description":"MB each person may add to \"From me\" per month (0–1000; 0 turns self upload off; default 100)."}},"required":["max_file_mb","ceiling_gb","self_files_per_month","self_mb_per_month"],"additionalProperties":false},"ceiling_max_gb":{"type":"integer","description":"The highest ceiling this company may set now."},"by_module":{"type":"array","items":{"type":"object","properties":{"module":{"type":"string"},"bytes":{"type":"integer"},"files":{"type":"integer"}},"required":["module","bytes","files"],"additionalProperties":false},"description":"documents = documents; org = profile photos; platform = the company logo."}},"required":["bytes","files","month","peak_bytes","free_bytes","unit_bytes","unit_price_cents","billable_units","estimated_cents","billed","limits","defaults","ceiling_max_gb","by_module"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/storage.set_limits":{"post":{"operationId":"platform.storage.set_limits","summary":"Change storage limits","description":"Changes the storage limits: largest file (1–100 MB), company ceiling (1–200 GB; at most 10 GB until paid billing is running), and self uploads per person per month (0–200 files and 0–1000 MB; 0 turns \"From me\" uploads off). Send only the limits to change. A ceiling below what is stored blocks new uploads until files are deleted; nothing is deleted. Owners and admins.","tags":["platform"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"max_file_mb":{"type":"integer","minimum":1,"maximum":100,"description":"Largest file, in MB (1–100; default 25)."},"ceiling_gb":{"type":"integer","minimum":1,"maximum":200,"description":"Company storage ceiling, in GB (1–200; at most 10 until paid billing is running; default 10)."},"self_files_per_month":{"type":"integer","minimum":0,"maximum":200,"description":"Files each person may add to \"From me\" per month (0–200; 0 turns self upload off; default 20)."},"self_mb_per_month":{"type":"integer","minimum":0,"maximum":1000,"description":"MB each person may add to \"From me\" per month (0–1000; 0 turns self upload off; default 100)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"bytes":{"type":"integer","description":"Bytes stored now: documents, profile photos and the company logo."},"files":{"type":"integer"},"month":{"type":"string","description":"The current billing month (YYYY-MM, UTC)."},"peak_bytes":{"type":"integer","description":"The highest size reached this month: what the month is billed on (deleting files does not lower it)."},"free_bytes":{"type":"integer","description":"Included in the price: 500 MB (decimal: 1 GB = 1000 MB)."},"unit_bytes":{"type":"integer","description":"One billing unit: 0.1 GB (100 MB)."},"unit_price_cents":{"type":"integer","description":"€0.10 per unit per month, excluding VAT (= €1 per GB)."},"billable_units":{"type":"integer","description":"ceil(max(0, peak − 500 MB) / 100 MB) for this month so far."},"estimated_cents":{"type":"integer","description":"billable_units × unit price, excluding VAT, for this month so far."},"billed":{"type":"boolean","description":"Storage is charged for this company (billing exists and has started); false before billing has started."},"limits":{"type":"object","properties":{"max_file_mb":{"type":"integer","minimum":1,"maximum":100,"description":"Largest file, in MB (1–100; default 25)."},"ceiling_gb":{"type":"integer","minimum":1,"maximum":200,"description":"Company storage ceiling, in GB (1–200; at most 10 until paid billing is running; default 10)."},"self_files_per_month":{"type":"integer","minimum":0,"maximum":200,"description":"Files each person may add to \"From me\" per month (0–200; 0 turns self upload off; default 20)."},"self_mb_per_month":{"type":"integer","minimum":0,"maximum":1000,"description":"MB each person may add to \"From me\" per month (0–1000; 0 turns self upload off; default 100)."}},"required":["max_file_mb","ceiling_gb","self_files_per_month","self_mb_per_month"],"additionalProperties":false},"defaults":{"type":"object","properties":{"max_file_mb":{"type":"integer","minimum":1,"maximum":100,"description":"Largest file, in MB (1–100; default 25)."},"ceiling_gb":{"type":"integer","minimum":1,"maximum":200,"description":"Company storage ceiling, in GB (1–200; at most 10 until paid billing is running; default 10)."},"self_files_per_month":{"type":"integer","minimum":0,"maximum":200,"description":"Files each person may add to \"From me\" per month (0–200; 0 turns self upload off; default 20)."},"self_mb_per_month":{"type":"integer","minimum":0,"maximum":1000,"description":"MB each person may add to \"From me\" per month (0–1000; 0 turns self upload off; default 100)."}},"required":["max_file_mb","ceiling_gb","self_files_per_month","self_mb_per_month"],"additionalProperties":false},"ceiling_max_gb":{"type":"integer","description":"The highest ceiling this company may set now."},"by_module":{"type":"array","items":{"type":"object","properties":{"module":{"type":"string"},"bytes":{"type":"integer"},"files":{"type":"integer"}},"required":["module","bytes","files"],"additionalProperties":false},"description":"documents = documents; org = profile photos; platform = the company logo."}},"required":["bytes","files","month","peak_bytes","free_bytes","unit_bytes","unit_price_cents","billable_units","estimated_cents","billed","limits","defaults","ceiling_max_gb","by_module"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/billing.get":{"post":{"operationId":"platform.billing.get","summary":"See billing","description":"Returns the organization's Bizisy plan: status (free_early_access before the start; free_first_month while the subscription's first, partial month is not charged, until starts_on; then active, past_due, needs_details, starting, paused or canceled; no card is needed: collection says whether invoices are charged to a card or emailed to pay), the active people count and billed quantity (at least 1), the unit price (€2.00 per active person per month, excluding VAT) and estimated monthly total, how VAT applies, the payment method summary (brand, last 4 digits, expiry; never the card number), the next charge date and the billing details, plus storage (500 MB included, then €1 per GB per month, i.e. €0.10 per 0.1 GB, on the month's highest size), optional emails (10 per active person per month included, pooled, then €1 per 1,000, i.e. €0.10 per block of 100) and the total so far. open_invoices lists the unpaid invoices (overdue ones flagged, overdue totals them) and pause says since when the company is paused and when it is closed if still unpaid. Billed monthly in arrears at the end of each calendar month for the people active then and the storage peak; the month billing starts in is not charged. Owners and admins only.","tags":["platform"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"mode":{"type":"string","enum":["test","live"],"description":"test: Stripe sandbox, nothing is really charged."},"status":{"type":"string","enum":["free_early_access","free_first_month","starting","needs_details","active","past_due","paused","canceled"],"description":"paused: an invoice is unpaid past its due date (or billing details are missing past their deadline): only owners and admins can sign in, to pay, save a card or export data; everything else is refused until it is paid. needs_details: billing has started and billing details are missing (no card is needed)."},"starts_on":{"type":"string","nullable":true,"description":"When this organization starts paying (YYYY-MM-DD, always a 1st): the 1st of the month after its start date (the announced date, never earlier than 30 days after its notice email), since the month billing starts in is not charged; null while no date is announced."},"active_people":{"type":"integer","description":"People active today (pre-hires and leavers are not counted)."},"quantity":{"type":"integer","description":"People billed: the active count, at least 1."},"unit_price_cents":{"type":"integer"},"currency":{"type":"string","enum":["EUR"]},"estimated_monthly_cents":{"type":"integer","description":"quantity × unit price, excluding VAT. Billed monthly in arrears at the end of each calendar month for the people active then."},"vat":{"type":"string","enum":["portuguese_vat","reverse_charge","export"],"nullable":true,"description":"How VAT applies (from the billing details); null without details."},"payment_method":{"type":"object","properties":{"brand":{"type":"string"},"last4":{"type":"string"},"exp_month":{"type":"integer"},"exp_year":{"type":"integer"}},"required":["brand","last4","exp_month","exp_year"],"additionalProperties":false,"nullable":true},"next_charge_on":{"type":"string","nullable":true,"description":"The next charge (a 1st: the end of the month being billed); during the uncharged first month, the end of the first paid month."},"cancel_at":{"type":"string","nullable":true,"description":"Set when the subscription was canceled: it ends (and access stays) until this date."},"details":{"type":"object","properties":{"legal_name":{"type":"string"},"vat_number":{"type":"string","nullable":true},"email":{"type":"string"},"address":{"type":"object","properties":{"line1":{"type":"string","minLength":1,"maxLength":200},"line2":{"type":"string","maxLength":200,"nullable":true},"city":{"type":"string","minLength":1,"maxLength":100},"postal_code":{"type":"string","minLength":1,"maxLength":20},"country":{"type":"string","pattern":"^[A-Z]{2}$"}},"required":["line1","line2","city","postal_code","country"],"additionalProperties":false},"vat_verification":{"type":"string","enum":["valid","invalid","unverified_network","unverified_error","not_applicable"],"nullable":true,"description":"EU VAT numbers outside Portugal are checked with the EU VIES service when saved: invalid means Portuguese VAT applies; unverified_network (VIES unreachable) and unverified_error (VIES refused the check; Bizisy is alerted) keep the format check until VIES answers. null on a dry run: the preview uses the format check and VIES is asked only when the change is saved."}},"required":["legal_name","vat_number","email","address","vat_verification"],"additionalProperties":false,"nullable":true},"billing_starts_on":{"type":"string","nullable":true,"description":"When billing starts for this organization (YYYY-MM-DD, Lisbon): from this day a payment method is needed; the month it falls in is not charged. null while no date is announced."},"first_charge_on":{"type":"string","nullable":true,"description":"When the payment method is first charged (YYYY-MM-DD, a 1st), while nothing has been charged yet: the end of the first paid month, since billing is monthly in arrears and the month billing starts in is not charged. null without an announced start date, once charging has begun, when the subscription is set to cancel, and for an organization subscribed before (a new subscription is then charged from its first month)."},"defaults":{"type":"object","properties":{"legal_name":{"type":"string"},"email":{"type":"string"},"country":{"type":"string"},"vat_number":{"type":"string","nullable":true,"description":"The legal entity's tax id, when it has one."},"source":{"type":"string","enum":["legal_entity","organization"],"description":"legal_entity: name, country and tax id come from the company's first legal entity; organization: from the company name and country."}},"required":["legal_name","email","country","vat_number","source"],"additionalProperties":false,"description":"Suggestions for an empty details form: the legal entity (or the company) and the caller's email."},"can_checkout":{"type":"boolean","description":"A card can be saved through Stripe Checkout (no card saved yet, or no running subscription; once a card pays, it changes in the portal). Saving one makes later invoices charged automatically."},"collection":{"type":"string","enum":["card","invoice"],"nullable":true,"description":"How invoices are paid: card (charged automatically) or invoice (emailed at month end, paid within 14 days on Stripe's page by card, SEPA Direct Debit or bank transfer); null before a subscription exists."},"open_invoice":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string","nullable":true},"amount_due_cents":{"type":"integer","description":"What is left to pay, VAT included."},"issued_on":{"type":"string","description":"YYYY-MM-DD (Lisbon) the invoice was issued."},"due_on":{"type":"string","description":"YYYY-MM-DD (Lisbon): if it is unpaid then, Bizisy pauses for everyone except owners and admins."},"days_left":{"type":"integer","description":"Whole days until due_on (0 = due today or past)."},"collection":{"type":"string","enum":["card","invoice"],"description":"card: a card payment that failed; invoice: emailed, paid on Stripe's page."},"overdue":{"type":"boolean","description":"Unpaid past the end of its due day (Lisbon): it counts toward the pause; paying every overdue invoice unpauses."}},"required":["id","number","amount_due_cents","issued_on","due_on","days_left","collection","overdue"],"additionalProperties":false,"nullable":true,"description":"The oldest unpaid invoice, if any."},"open_invoices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string","nullable":true},"amount_due_cents":{"type":"integer","description":"What is left to pay, VAT included."},"issued_on":{"type":"string","description":"YYYY-MM-DD (Lisbon) the invoice was issued."},"due_on":{"type":"string","description":"YYYY-MM-DD (Lisbon): if it is unpaid then, Bizisy pauses for everyone except owners and admins."},"days_left":{"type":"integer","description":"Whole days until due_on (0 = due today or past)."},"collection":{"type":"string","enum":["card","invoice"],"description":"card: a card payment that failed; invoice: emailed, paid on Stripe's page."},"overdue":{"type":"boolean","description":"Unpaid past the end of its due day (Lisbon): it counts toward the pause; paying every overdue invoice unpauses."}},"required":["id","number","amount_due_cents","issued_on","due_on","days_left","collection","overdue"],"additionalProperties":false},"description":"Every unpaid invoice, oldest first (at most 12). Billing continues while paused, so there may be several."},"overdue":{"type":"object","properties":{"count":{"type":"integer"},"total_cents":{"type":"integer"}},"required":["count","total_cents"],"additionalProperties":false,"nullable":true,"description":"Unpaid invoices past the end of their due day: every one must be paid to lift a pause (or reopen a company closed for non-payment)."},"pause":{"type":"object","properties":{"reason":{"type":"string","enum":["unpaid","details_missing"]},"since":{"type":"string","description":"YYYY-MM-DD (Lisbon)."},"closes_on":{"type":"string","description":"YYYY-MM-DD: if still unpaid then, the company account is closed (deleted 14 days later unless paid)."}},"required":["reason","since","closes_on"],"additionalProperties":false,"nullable":true,"description":"Set while the company is paused (pay-or-lock)."},"details_due_on":{"type":"string","nullable":true,"description":"needs_details: YYYY-MM-DD when Bizisy pauses if billing details are still missing."},"can_open_portal":{"type":"boolean","description":"The Stripe customer portal exists (after the first checkout)."},"storage":{"type":"object","properties":{"bytes":{"type":"integer","description":"Stored now (documents, photos, logo)."},"peak_bytes":{"type":"integer","description":"This month's highest size: what storage is billed on."},"free_bytes":{"type":"integer","description":"Included: 500 MB."},"unit_bytes":{"type":"integer","description":"One unit: 0.1 GB."},"billable_units":{"type":"integer"},"unit_price_cents":{"type":"integer","description":"€0.10 per unit per month, excluding VAT (€1 per GB)."},"estimated_cents":{"type":"integer","description":"This month's storage so far, excluding VAT; billed with the people at month end."}},"required":["bytes","peak_bytes","free_bytes","unit_bytes","billable_units","unit_price_cents","estimated_cents"],"additionalProperties":false,"nullable":true,"description":"Storage above 500 MB (documents); null where the server has no file storage."},"email":{"type":"object","properties":{"sent":{"type":"integer","description":"Optional emails sent this month (reminders and task digests, approval requests, document notices; a digest is one)."},"allowance":{"type":"integer","description":"Included this month: 10 per person billed, pooled."},"billable_units":{"type":"integer","description":"Blocks of 100 emails above the allowance, rounded up."},"unit_size":{"type":"integer"},"unit_price_cents":{"type":"integer","description":"€0.10 per block of 100, excluding VAT (= €1 per 1,000)."},"estimated_cents":{"type":"integer","description":"This month's optional emails above the allowance so far, excluding VAT (counted even when not billed)."},"billed":{"type":"boolean","description":"These are charged this month (a paid subscription with the email price, on or after billing_from); false: included, and left out of estimated_total_cents."},"billing_from":{"type":"string","nullable":true,"description":"YYYY-MM-DD (a 1st): from when they are charged, at least 30 days after the owners and admins were told the price; null until they were told."}},"required":["sent","allowance","billable_units","unit_size","unit_price_cents","estimated_cents","billed","billing_from"],"additionalProperties":false,"description":"Optional emails above the allowance (Settings → Notifications)."},"estimated_total_cents":{"type":"integer","description":"People, storage and optional emails so far this month, excluding VAT."}},"required":["mode","status","starts_on","active_people","quantity","unit_price_cents","currency","estimated_monthly_cents","vat","payment_method","next_charge_on","cancel_at","details","billing_starts_on","first_charge_on","defaults","can_checkout","collection","open_invoice","open_invoices","overdue","pause","details_due_on","can_open_portal","storage","email","estimated_total_cents"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"platform.billing.get","summary":"See billing","description":"Returns the organization's Bizisy plan: status (free_early_access before the start; free_first_month while the subscription's first, partial month is not charged, until starts_on; then active, past_due, needs_details, starting, paused or canceled; no card is needed: collection says whether invoices are charged to a card or emailed to pay), the active people count and billed quantity (at least 1), the unit price (€2.00 per active person per month, excluding VAT) and estimated monthly total, how VAT applies, the payment method summary (brand, last 4 digits, expiry; never the card number), the next charge date and the billing details, plus storage (500 MB included, then €1 per GB per month, i.e. €0.10 per 0.1 GB, on the month's highest size), optional emails (10 per active person per month included, pooled, then €1 per 1,000, i.e. €0.10 per block of 100) and the total so far. open_invoices lists the unpaid invoices (overdue ones flagged, overdue totals them) and pause says since when the company is paused and when it is closed if still unpaid. Billed monthly in arrears at the end of each calendar month for the people active then and the storage peak; the month billing starts in is not charged. Owners and admins only.","tags":["platform"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"mode":{"type":"string","enum":["test","live"],"description":"test: Stripe sandbox, nothing is really charged."},"status":{"type":"string","enum":["free_early_access","free_first_month","starting","needs_details","active","past_due","paused","canceled"],"description":"paused: an invoice is unpaid past its due date (or billing details are missing past their deadline): only owners and admins can sign in, to pay, save a card or export data; everything else is refused until it is paid. needs_details: billing has started and billing details are missing (no card is needed)."},"starts_on":{"type":"string","nullable":true,"description":"When this organization starts paying (YYYY-MM-DD, always a 1st): the 1st of the month after its start date (the announced date, never earlier than 30 days after its notice email), since the month billing starts in is not charged; null while no date is announced."},"active_people":{"type":"integer","description":"People active today (pre-hires and leavers are not counted)."},"quantity":{"type":"integer","description":"People billed: the active count, at least 1."},"unit_price_cents":{"type":"integer"},"currency":{"type":"string","enum":["EUR"]},"estimated_monthly_cents":{"type":"integer","description":"quantity × unit price, excluding VAT. Billed monthly in arrears at the end of each calendar month for the people active then."},"vat":{"type":"string","enum":["portuguese_vat","reverse_charge","export"],"nullable":true,"description":"How VAT applies (from the billing details); null without details."},"payment_method":{"type":"object","properties":{"brand":{"type":"string"},"last4":{"type":"string"},"exp_month":{"type":"integer"},"exp_year":{"type":"integer"}},"required":["brand","last4","exp_month","exp_year"],"additionalProperties":false,"nullable":true},"next_charge_on":{"type":"string","nullable":true,"description":"The next charge (a 1st: the end of the month being billed); during the uncharged first month, the end of the first paid month."},"cancel_at":{"type":"string","nullable":true,"description":"Set when the subscription was canceled: it ends (and access stays) until this date."},"details":{"type":"object","properties":{"legal_name":{"type":"string"},"vat_number":{"type":"string","nullable":true},"email":{"type":"string"},"address":{"type":"object","properties":{"line1":{"type":"string","minLength":1,"maxLength":200},"line2":{"type":"string","maxLength":200,"nullable":true},"city":{"type":"string","minLength":1,"maxLength":100},"postal_code":{"type":"string","minLength":1,"maxLength":20},"country":{"type":"string","pattern":"^[A-Z]{2}$"}},"required":["line1","line2","city","postal_code","country"],"additionalProperties":false},"vat_verification":{"type":"string","enum":["valid","invalid","unverified_network","unverified_error","not_applicable"],"nullable":true,"description":"EU VAT numbers outside Portugal are checked with the EU VIES service when saved: invalid means Portuguese VAT applies; unverified_network (VIES unreachable) and unverified_error (VIES refused the check; Bizisy is alerted) keep the format check until VIES answers. null on a dry run: the preview uses the format check and VIES is asked only when the change is saved."}},"required":["legal_name","vat_number","email","address","vat_verification"],"additionalProperties":false,"nullable":true},"billing_starts_on":{"type":"string","nullable":true,"description":"When billing starts for this organization (YYYY-MM-DD, Lisbon): from this day a payment method is needed; the month it falls in is not charged. null while no date is announced."},"first_charge_on":{"type":"string","nullable":true,"description":"When the payment method is first charged (YYYY-MM-DD, a 1st), while nothing has been charged yet: the end of the first paid month, since billing is monthly in arrears and the month billing starts in is not charged. null without an announced start date, once charging has begun, when the subscription is set to cancel, and for an organization subscribed before (a new subscription is then charged from its first month)."},"defaults":{"type":"object","properties":{"legal_name":{"type":"string"},"email":{"type":"string"},"country":{"type":"string"},"vat_number":{"type":"string","nullable":true,"description":"The legal entity's tax id, when it has one."},"source":{"type":"string","enum":["legal_entity","organization"],"description":"legal_entity: name, country and tax id come from the company's first legal entity; organization: from the company name and country."}},"required":["legal_name","email","country","vat_number","source"],"additionalProperties":false,"description":"Suggestions for an empty details form: the legal entity (or the company) and the caller's email."},"can_checkout":{"type":"boolean","description":"A card can be saved through Stripe Checkout (no card saved yet, or no running subscription; once a card pays, it changes in the portal). Saving one makes later invoices charged automatically."},"collection":{"type":"string","enum":["card","invoice"],"nullable":true,"description":"How invoices are paid: card (charged automatically) or invoice (emailed at month end, paid within 14 days on Stripe's page by card, SEPA Direct Debit or bank transfer); null before a subscription exists."},"open_invoice":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string","nullable":true},"amount_due_cents":{"type":"integer","description":"What is left to pay, VAT included."},"issued_on":{"type":"string","description":"YYYY-MM-DD (Lisbon) the invoice was issued."},"due_on":{"type":"string","description":"YYYY-MM-DD (Lisbon): if it is unpaid then, Bizisy pauses for everyone except owners and admins."},"days_left":{"type":"integer","description":"Whole days until due_on (0 = due today or past)."},"collection":{"type":"string","enum":["card","invoice"],"description":"card: a card payment that failed; invoice: emailed, paid on Stripe's page."},"overdue":{"type":"boolean","description":"Unpaid past the end of its due day (Lisbon): it counts toward the pause; paying every overdue invoice unpauses."}},"required":["id","number","amount_due_cents","issued_on","due_on","days_left","collection","overdue"],"additionalProperties":false,"nullable":true,"description":"The oldest unpaid invoice, if any."},"open_invoices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string","nullable":true},"amount_due_cents":{"type":"integer","description":"What is left to pay, VAT included."},"issued_on":{"type":"string","description":"YYYY-MM-DD (Lisbon) the invoice was issued."},"due_on":{"type":"string","description":"YYYY-MM-DD (Lisbon): if it is unpaid then, Bizisy pauses for everyone except owners and admins."},"days_left":{"type":"integer","description":"Whole days until due_on (0 = due today or past)."},"collection":{"type":"string","enum":["card","invoice"],"description":"card: a card payment that failed; invoice: emailed, paid on Stripe's page."},"overdue":{"type":"boolean","description":"Unpaid past the end of its due day (Lisbon): it counts toward the pause; paying every overdue invoice unpauses."}},"required":["id","number","amount_due_cents","issued_on","due_on","days_left","collection","overdue"],"additionalProperties":false},"description":"Every unpaid invoice, oldest first (at most 12). Billing continues while paused, so there may be several."},"overdue":{"type":"object","properties":{"count":{"type":"integer"},"total_cents":{"type":"integer"}},"required":["count","total_cents"],"additionalProperties":false,"nullable":true,"description":"Unpaid invoices past the end of their due day: every one must be paid to lift a pause (or reopen a company closed for non-payment)."},"pause":{"type":"object","properties":{"reason":{"type":"string","enum":["unpaid","details_missing"]},"since":{"type":"string","description":"YYYY-MM-DD (Lisbon)."},"closes_on":{"type":"string","description":"YYYY-MM-DD: if still unpaid then, the company account is closed (deleted 14 days later unless paid)."}},"required":["reason","since","closes_on"],"additionalProperties":false,"nullable":true,"description":"Set while the company is paused (pay-or-lock)."},"details_due_on":{"type":"string","nullable":true,"description":"needs_details: YYYY-MM-DD when Bizisy pauses if billing details are still missing."},"can_open_portal":{"type":"boolean","description":"The Stripe customer portal exists (after the first checkout)."},"storage":{"type":"object","properties":{"bytes":{"type":"integer","description":"Stored now (documents, photos, logo)."},"peak_bytes":{"type":"integer","description":"This month's highest size: what storage is billed on."},"free_bytes":{"type":"integer","description":"Included: 500 MB."},"unit_bytes":{"type":"integer","description":"One unit: 0.1 GB."},"billable_units":{"type":"integer"},"unit_price_cents":{"type":"integer","description":"€0.10 per unit per month, excluding VAT (€1 per GB)."},"estimated_cents":{"type":"integer","description":"This month's storage so far, excluding VAT; billed with the people at month end."}},"required":["bytes","peak_bytes","free_bytes","unit_bytes","billable_units","unit_price_cents","estimated_cents"],"additionalProperties":false,"nullable":true,"description":"Storage above 500 MB (documents); null where the server has no file storage."},"email":{"type":"object","properties":{"sent":{"type":"integer","description":"Optional emails sent this month (reminders and task digests, approval requests, document notices; a digest is one)."},"allowance":{"type":"integer","description":"Included this month: 10 per person billed, pooled."},"billable_units":{"type":"integer","description":"Blocks of 100 emails above the allowance, rounded up."},"unit_size":{"type":"integer"},"unit_price_cents":{"type":"integer","description":"€0.10 per block of 100, excluding VAT (= €1 per 1,000)."},"estimated_cents":{"type":"integer","description":"This month's optional emails above the allowance so far, excluding VAT (counted even when not billed)."},"billed":{"type":"boolean","description":"These are charged this month (a paid subscription with the email price, on or after billing_from); false: included, and left out of estimated_total_cents."},"billing_from":{"type":"string","nullable":true,"description":"YYYY-MM-DD (a 1st): from when they are charged, at least 30 days after the owners and admins were told the price; null until they were told."}},"required":["sent","allowance","billable_units","unit_size","unit_price_cents","estimated_cents","billed","billing_from"],"additionalProperties":false,"description":"Optional emails above the allowance (Settings → Notifications)."},"estimated_total_cents":{"type":"integer","description":"People, storage and optional emails so far this month, excluding VAT."}},"required":["mode","status","starts_on","active_people","quantity","unit_price_cents","currency","estimated_monthly_cents","vat","payment_method","next_charge_on","cancel_at","details","billing_starts_on","first_charge_on","defaults","can_checkout","collection","open_invoice","open_invoices","overdue","pause","details_due_on","can_open_portal","storage","email","estimated_total_cents"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/billing.update_details":{"post":{"operationId":"platform.billing.update_details","summary":"Change billing details","description":"Sets the billing details printed on invoices: legal_name, vat_number (NIF in Portugal, required and checked: companies and sole traders; EU VAT numbers get their country prefix and a format check), email (where invoices go) and address { line1, line2?, city, postal_code, country }. Send the whole set every time. The country and VAT number decide VAT: Portugal (and EU without a VAT number) pays Portuguese VAT, EU businesses with a VAT number are reverse charged, outside the EU is exempt. Owners and admins only; preview with dry_run.","tags":["platform"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"legal_name":{"type":"string","minLength":2,"maxLength":200,"description":"The legal name on invoices, e.g. \"Acme, Lda\"."},"vat_number":{"type":"string","maxLength":40,"nullable":true,"description":"NIF / VAT number. Required in Portugal (a valid NIF of a company or sole trader: first digit 1, 2, 3, 5, 6, 8 or 9; 999999990 refused); EU numbers get their country prefix; optional outside Portugal."},"email":{"type":"string","format":"email","maxLength":254,"description":"Where invoices and billing emails go."},"address":{"type":"object","properties":{"line1":{"type":"string","minLength":1,"maxLength":200},"line2":{"type":"string","maxLength":200,"nullable":true},"city":{"type":"string","minLength":1,"maxLength":100},"postal_code":{"type":"string","minLength":1,"maxLength":20},"country":{"allOf":[{"type":"string"},{"type":"string","pattern":"^[A-Z]{2}$"}],"description":"ISO 3166 two-letter code, e.g. PT."}},"required":["line1","city","postal_code","country"],"additionalProperties":false}},"required":["legal_name","email","address"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"mode":{"type":"string","enum":["test","live"],"description":"test: Stripe sandbox, nothing is really charged."},"status":{"type":"string","enum":["free_early_access","free_first_month","starting","needs_details","active","past_due","paused","canceled"],"description":"paused: an invoice is unpaid past its due date (or billing details are missing past their deadline): only owners and admins can sign in, to pay, save a card or export data; everything else is refused until it is paid. needs_details: billing has started and billing details are missing (no card is needed)."},"starts_on":{"type":"string","nullable":true,"description":"When this organization starts paying (YYYY-MM-DD, always a 1st): the 1st of the month after its start date (the announced date, never earlier than 30 days after its notice email), since the month billing starts in is not charged; null while no date is announced."},"active_people":{"type":"integer","description":"People active today (pre-hires and leavers are not counted)."},"quantity":{"type":"integer","description":"People billed: the active count, at least 1."},"unit_price_cents":{"type":"integer"},"currency":{"type":"string","enum":["EUR"]},"estimated_monthly_cents":{"type":"integer","description":"quantity × unit price, excluding VAT. Billed monthly in arrears at the end of each calendar month for the people active then."},"vat":{"type":"string","enum":["portuguese_vat","reverse_charge","export"],"nullable":true,"description":"How VAT applies (from the billing details); null without details."},"payment_method":{"type":"object","properties":{"brand":{"type":"string"},"last4":{"type":"string"},"exp_month":{"type":"integer"},"exp_year":{"type":"integer"}},"required":["brand","last4","exp_month","exp_year"],"additionalProperties":false,"nullable":true},"next_charge_on":{"type":"string","nullable":true,"description":"The next charge (a 1st: the end of the month being billed); during the uncharged first month, the end of the first paid month."},"cancel_at":{"type":"string","nullable":true,"description":"Set when the subscription was canceled: it ends (and access stays) until this date."},"details":{"type":"object","properties":{"legal_name":{"type":"string"},"vat_number":{"type":"string","nullable":true},"email":{"type":"string"},"address":{"type":"object","properties":{"line1":{"type":"string","minLength":1,"maxLength":200},"line2":{"type":"string","maxLength":200,"nullable":true},"city":{"type":"string","minLength":1,"maxLength":100},"postal_code":{"type":"string","minLength":1,"maxLength":20},"country":{"type":"string","pattern":"^[A-Z]{2}$"}},"required":["line1","line2","city","postal_code","country"],"additionalProperties":false},"vat_verification":{"type":"string","enum":["valid","invalid","unverified_network","unverified_error","not_applicable"],"nullable":true,"description":"EU VAT numbers outside Portugal are checked with the EU VIES service when saved: invalid means Portuguese VAT applies; unverified_network (VIES unreachable) and unverified_error (VIES refused the check; Bizisy is alerted) keep the format check until VIES answers. null on a dry run: the preview uses the format check and VIES is asked only when the change is saved."}},"required":["legal_name","vat_number","email","address","vat_verification"],"additionalProperties":false,"nullable":true},"billing_starts_on":{"type":"string","nullable":true,"description":"When billing starts for this organization (YYYY-MM-DD, Lisbon): from this day a payment method is needed; the month it falls in is not charged. null while no date is announced."},"first_charge_on":{"type":"string","nullable":true,"description":"When the payment method is first charged (YYYY-MM-DD, a 1st), while nothing has been charged yet: the end of the first paid month, since billing is monthly in arrears and the month billing starts in is not charged. null without an announced start date, once charging has begun, when the subscription is set to cancel, and for an organization subscribed before (a new subscription is then charged from its first month)."},"defaults":{"type":"object","properties":{"legal_name":{"type":"string"},"email":{"type":"string"},"country":{"type":"string"},"vat_number":{"type":"string","nullable":true,"description":"The legal entity's tax id, when it has one."},"source":{"type":"string","enum":["legal_entity","organization"],"description":"legal_entity: name, country and tax id come from the company's first legal entity; organization: from the company name and country."}},"required":["legal_name","email","country","vat_number","source"],"additionalProperties":false,"description":"Suggestions for an empty details form: the legal entity (or the company) and the caller's email."},"can_checkout":{"type":"boolean","description":"A card can be saved through Stripe Checkout (no card saved yet, or no running subscription; once a card pays, it changes in the portal). Saving one makes later invoices charged automatically."},"collection":{"type":"string","enum":["card","invoice"],"nullable":true,"description":"How invoices are paid: card (charged automatically) or invoice (emailed at month end, paid within 14 days on Stripe's page by card, SEPA Direct Debit or bank transfer); null before a subscription exists."},"open_invoice":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string","nullable":true},"amount_due_cents":{"type":"integer","description":"What is left to pay, VAT included."},"issued_on":{"type":"string","description":"YYYY-MM-DD (Lisbon) the invoice was issued."},"due_on":{"type":"string","description":"YYYY-MM-DD (Lisbon): if it is unpaid then, Bizisy pauses for everyone except owners and admins."},"days_left":{"type":"integer","description":"Whole days until due_on (0 = due today or past)."},"collection":{"type":"string","enum":["card","invoice"],"description":"card: a card payment that failed; invoice: emailed, paid on Stripe's page."},"overdue":{"type":"boolean","description":"Unpaid past the end of its due day (Lisbon): it counts toward the pause; paying every overdue invoice unpauses."}},"required":["id","number","amount_due_cents","issued_on","due_on","days_left","collection","overdue"],"additionalProperties":false,"nullable":true,"description":"The oldest unpaid invoice, if any."},"open_invoices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string","nullable":true},"amount_due_cents":{"type":"integer","description":"What is left to pay, VAT included."},"issued_on":{"type":"string","description":"YYYY-MM-DD (Lisbon) the invoice was issued."},"due_on":{"type":"string","description":"YYYY-MM-DD (Lisbon): if it is unpaid then, Bizisy pauses for everyone except owners and admins."},"days_left":{"type":"integer","description":"Whole days until due_on (0 = due today or past)."},"collection":{"type":"string","enum":["card","invoice"],"description":"card: a card payment that failed; invoice: emailed, paid on Stripe's page."},"overdue":{"type":"boolean","description":"Unpaid past the end of its due day (Lisbon): it counts toward the pause; paying every overdue invoice unpauses."}},"required":["id","number","amount_due_cents","issued_on","due_on","days_left","collection","overdue"],"additionalProperties":false},"description":"Every unpaid invoice, oldest first (at most 12). Billing continues while paused, so there may be several."},"overdue":{"type":"object","properties":{"count":{"type":"integer"},"total_cents":{"type":"integer"}},"required":["count","total_cents"],"additionalProperties":false,"nullable":true,"description":"Unpaid invoices past the end of their due day: every one must be paid to lift a pause (or reopen a company closed for non-payment)."},"pause":{"type":"object","properties":{"reason":{"type":"string","enum":["unpaid","details_missing"]},"since":{"type":"string","description":"YYYY-MM-DD (Lisbon)."},"closes_on":{"type":"string","description":"YYYY-MM-DD: if still unpaid then, the company account is closed (deleted 14 days later unless paid)."}},"required":["reason","since","closes_on"],"additionalProperties":false,"nullable":true,"description":"Set while the company is paused (pay-or-lock)."},"details_due_on":{"type":"string","nullable":true,"description":"needs_details: YYYY-MM-DD when Bizisy pauses if billing details are still missing."},"can_open_portal":{"type":"boolean","description":"The Stripe customer portal exists (after the first checkout)."},"storage":{"type":"object","properties":{"bytes":{"type":"integer","description":"Stored now (documents, photos, logo)."},"peak_bytes":{"type":"integer","description":"This month's highest size: what storage is billed on."},"free_bytes":{"type":"integer","description":"Included: 500 MB."},"unit_bytes":{"type":"integer","description":"One unit: 0.1 GB."},"billable_units":{"type":"integer"},"unit_price_cents":{"type":"integer","description":"€0.10 per unit per month, excluding VAT (€1 per GB)."},"estimated_cents":{"type":"integer","description":"This month's storage so far, excluding VAT; billed with the people at month end."}},"required":["bytes","peak_bytes","free_bytes","unit_bytes","billable_units","unit_price_cents","estimated_cents"],"additionalProperties":false,"nullable":true,"description":"Storage above 500 MB (documents); null where the server has no file storage."},"email":{"type":"object","properties":{"sent":{"type":"integer","description":"Optional emails sent this month (reminders and task digests, approval requests, document notices; a digest is one)."},"allowance":{"type":"integer","description":"Included this month: 10 per person billed, pooled."},"billable_units":{"type":"integer","description":"Blocks of 100 emails above the allowance, rounded up."},"unit_size":{"type":"integer"},"unit_price_cents":{"type":"integer","description":"€0.10 per block of 100, excluding VAT (= €1 per 1,000)."},"estimated_cents":{"type":"integer","description":"This month's optional emails above the allowance so far, excluding VAT (counted even when not billed)."},"billed":{"type":"boolean","description":"These are charged this month (a paid subscription with the email price, on or after billing_from); false: included, and left out of estimated_total_cents."},"billing_from":{"type":"string","nullable":true,"description":"YYYY-MM-DD (a 1st): from when they are charged, at least 30 days after the owners and admins were told the price; null until they were told."}},"required":["sent","allowance","billable_units","unit_size","unit_price_cents","estimated_cents","billed","billing_from"],"additionalProperties":false,"description":"Optional emails above the allowance (Settings → Notifications)."},"estimated_total_cents":{"type":"integer","description":"People, storage and optional emails so far this month, excluding VAT."}},"required":["mode","status","starts_on","active_people","quantity","unit_price_cents","currency","estimated_monthly_cents","vat","payment_method","next_charge_on","cancel_at","details","billing_starts_on","first_charge_on","defaults","can_checkout","collection","open_invoice","open_invoices","overdue","pause","details_due_on","can_open_portal","storage","email","estimated_total_cents"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/billing.checkout":{"post":{"operationId":"platform.billing.checkout","summary":"Add a payment method","description":"Web app only: starts a Stripe Checkout page that saves a payment method and returns its short-lived url. Nothing is charged on that page: from the start date, Bizisy subscribes the organization itself and charges the saved method monthly in arrears at the end of each calendar month (€2 per active person, excluding VAT, plus VAT where it applies); the month the subscription starts in is not charged. Needs billing details first; once the subscription runs, the card changes in the billing portal. Refused for API keys and AI assistants: tell the user to open Settings → Billing in Bizisy. Owners and admins only.","tags":["platform"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"url":{"type":"string","nullable":true,"description":"Null on a dry run."},"mode":{"type":"string","enum":["setup"]}},"required":["url","mode"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/billing.portal":{"post":{"operationId":"platform.billing.portal","summary":"Open the billing portal","description":"Web app only: returns a short-lived url to Stripe's customer portal, where the user changes the payment method, downloads Stripe receipts or cancels (at the end of the period already paid). Refused for API keys and AI assistants: tell the user to open Settings → Billing in Bizisy. Owners and admins only; needs a first checkout.","tags":["platform"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"url":{"type":"string","nullable":true,"description":"Null on a dry run."}},"required":["url"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/billing.invoices.list":{"post":{"operationId":"platform.billing.invoices.list","summary":"List invoices","description":"Lists the organization's Bizisy invoices with an amount to pay, newest first (at most 100; €0 invoices such as the uncharged first month are left out): date, period, people billed, total with and without VAT, payment status (paid, open, failed), the certified invoice (fatura) number and status, and Stripe's receipt page. Owners and admins only.","tags":["platform"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string","nullable":true},"date":{"type":"string"},"period_start":{"type":"string","nullable":true},"period_end":{"type":"string","nullable":true},"quantity":{"type":"integer"},"total_cents":{"type":"integer"},"total_excluding_vat_cents":{"type":"integer"},"currency":{"type":"string"},"status":{"type":"string","enum":["paid","open","failed","void","uncollectible"]},"fatura":{"type":"object","properties":{"status":{"type":"string","enum":["pending","issued","failed","test"],"description":"The certified invoice (fatura): pending = being issued (retrying); issued = final; failed = delayed, Bizisy issues it by hand; test = test mode, no fatura is issued."},"number":{"type":"string","nullable":true}},"required":["status","number"],"additionalProperties":false},"receipt_url":{"type":"string","nullable":true,"description":"Stripe's payment receipt page."}},"required":["id","number","date","period_start","period_end","quantity","total_cents","total_excluding_vat_cents","currency","status","fatura","receipt_url"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"platform.billing.invoices.list","summary":"List invoices","description":"Lists the organization's Bizisy invoices with an amount to pay, newest first (at most 100; €0 invoices such as the uncharged first month are left out): date, period, people billed, total with and without VAT, payment status (paid, open, failed), the certified invoice (fatura) number and status, and Stripe's receipt page. Owners and admins only.","tags":["platform"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string","nullable":true},"date":{"type":"string"},"period_start":{"type":"string","nullable":true},"period_end":{"type":"string","nullable":true},"quantity":{"type":"integer"},"total_cents":{"type":"integer"},"total_excluding_vat_cents":{"type":"integer"},"currency":{"type":"string"},"status":{"type":"string","enum":["paid","open","failed","void","uncollectible"]},"fatura":{"type":"object","properties":{"status":{"type":"string","enum":["pending","issued","failed","test"],"description":"The certified invoice (fatura): pending = being issued (retrying); issued = final; failed = delayed, Bizisy issues it by hand; test = test mode, no fatura is issued."},"number":{"type":"string","nullable":true}},"required":["status","number"],"additionalProperties":false},"receipt_url":{"type":"string","nullable":true,"description":"Stripe's payment receipt page."}},"required":["id","number","date","period_start","period_end","quantity","total_cents","total_excluding_vat_cents","currency","status","fatura","receipt_url"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/billing.invoices.pdf":{"post":{"operationId":"platform.billing.invoices.pdf","summary":"Download a certified invoice","description":"Web app only: returns a download link to the certified invoice (fatura) PDF of one paid invoice (invoice_id from platform_billing_invoices_list), valid for a few seconds. Only for issued faturas. Refused for API keys and AI assistants. Owners and admins only.","tags":["platform"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string","minLength":1,"maxLength":100}},"required":["invoice_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"platform.billing.invoices.pdf","summary":"Download a certified invoice","description":"Web app only: returns a download link to the certified invoice (fatura) PDF of one paid invoice (invoice_id from platform_billing_invoices_list), valid for a few seconds. Only for issued faturas. Refused for API keys and AI assistants. Owners and admins only.","tags":["platform"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/platform/billing.pay":{"post":{"operationId":"platform.billing.pay","summary":"Pay an open invoice","description":"Web app only: returns Stripe's payment page for the oldest unpaid Bizisy invoice (or invoice_id from platform_billing_get open_invoice), fetched now and never stored. On that page an owner or admin pays by card, SEPA Direct Debit or bank transfer; paying a paused company's overdue invoice unpauses it at once. Refused for API keys and AI assistants: tell the user to open Settings → Billing in Bizisy and choose Pay now. Owners and admins only.","tags":["platform"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string","minLength":1,"maxLength":100}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"url":{"type":"string"},"invoice":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string","nullable":true},"amount_due_cents":{"type":"integer","description":"What is left to pay, VAT included."},"issued_on":{"type":"string","description":"YYYY-MM-DD (Lisbon) the invoice was issued."},"due_on":{"type":"string","description":"YYYY-MM-DD (Lisbon): if it is unpaid then, Bizisy pauses for everyone except owners and admins."},"days_left":{"type":"integer","description":"Whole days until due_on (0 = due today or past)."},"collection":{"type":"string","enum":["card","invoice"],"description":"card: a card payment that failed; invoice: emailed, paid on Stripe's page."},"overdue":{"type":"boolean","description":"Unpaid past the end of its due day (Lisbon): it counts toward the pause; paying every overdue invoice unpauses."}},"required":["id","number","amount_due_cents","issued_on","due_on","days_left","collection","overdue"],"additionalProperties":false}},"required":["url","invoice"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"platform.billing.pay","summary":"Pay an open invoice","description":"Web app only: returns Stripe's payment page for the oldest unpaid Bizisy invoice (or invoice_id from platform_billing_get open_invoice), fetched now and never stored. On that page an owner or admin pays by card, SEPA Direct Debit or bank transfer; paying a paused company's overdue invoice unpauses it at once. Refused for API keys and AI assistants: tell the user to open Settings → Billing in Bizisy and choose Pay now. Owners and admins only.","tags":["platform"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"url":{"type":"string"},"invoice":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string","nullable":true},"amount_due_cents":{"type":"integer","description":"What is left to pay, VAT included."},"issued_on":{"type":"string","description":"YYYY-MM-DD (Lisbon) the invoice was issued."},"due_on":{"type":"string","description":"YYYY-MM-DD (Lisbon): if it is unpaid then, Bizisy pauses for everyone except owners and admins."},"days_left":{"type":"integer","description":"Whole days until due_on (0 = due today or past)."},"collection":{"type":"string","enum":["card","invoice"],"description":"card: a card payment that failed; invoice: emailed, paid on Stripe's page."},"overdue":{"type":"boolean","description":"Unpaid past the end of its due day (Lisbon): it counts toward the pause; paying every overdue invoice unpauses."}},"required":["id","number","amount_due_cents","issued_on","due_on","days_left","collection","overdue"],"additionalProperties":false}},"required":["url","invoice"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/setup.init":{"post":{"operationId":"org.setup.init","summary":"Initialise the company (idempotent)","description":"Creates whatever is missing of: the legal entity (company name and country), a \"Head office\" location, the company root unit, the org settings, and your own person record (job title \"Founder\" unless owner_title is given, starting today) linked to your login. Only owners and admins can link their own login; for anyone else the person is created and warnings asks an owner or admin to link it with platform_members_link_person. Safe to call any number of times; call it first on a new company. Returns the setup checklist plus warnings.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"owner_title":{"type":"string","minLength":1,"maxLength":120}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"entity":{"type":"boolean"},"location":{"type":"boolean"},"units":{"type":"boolean"},"people":{"type":"boolean"},"invited":{"type":"boolean"},"ai_connected":{"type":"boolean"},"completed":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["entity","location","units","people","invited","ai_connected","completed","warnings"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/setup.status":{"post":{"operationId":"org.setup.status","summary":"Setup checklist","description":"Returns which setup steps are done: entity, location, units (more than the root), people (more than the owner), invited (at least one invite), ai_connected (a manage API key exists) and completed (all but ai_connected). Use it to decide what to do next.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"entity":{"type":"boolean"},"location":{"type":"boolean"},"units":{"type":"boolean"},"people":{"type":"boolean"},"invited":{"type":"boolean"},"ai_connected":{"type":"boolean"},"completed":{"type":"boolean"}},"required":["entity","location","units","people","invited","ai_connected","completed"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.setup.status","summary":"Setup checklist","description":"Returns which setup steps are done: entity, location, units (more than the root), people (more than the owner), invited (at least one invite), ai_connected (a manage API key exists) and completed (all but ai_connected). Use it to decide what to do next.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"entity":{"type":"boolean"},"location":{"type":"boolean"},"units":{"type":"boolean"},"people":{"type":"boolean"},"invited":{"type":"boolean"},"ai_connected":{"type":"boolean"},"completed":{"type":"boolean"}},"required":["entity","location","units","people","invited","ai_connected","completed"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/units.list":{"post":{"operationId":"org.units.list","summary":"List units (company, divisions, departments, teams)","description":"Lists the org structure as a flat list (root first, then by depth and name). Each unit has parent_id, head (its team lead: the default manager of people who join it, and who approves in place of a missing manager) and member_count (people currently assigned directly). Archived units are hidden unless include_archived is true.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"include_archived":{"type":"boolean","default":false,"description":"Also return archived items."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["company","division","department","team"]},"parent_id":{"type":"string","nullable":true},"head":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"archived":{"type":"boolean"},"member_count":{"type":"integer"}},"required":["id","name","kind","parent_id","head","archived","member_count"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.units.list","summary":"List units (company, divisions, departments, teams)","description":"Lists the org structure as a flat list (root first, then by depth and name). Each unit has parent_id, head (its team lead: the default manager of people who join it, and who approves in place of a missing manager) and member_count (people currently assigned directly). Archived units are hidden unless include_archived is true.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["company","division","department","team"]},"parent_id":{"type":"string","nullable":true},"head":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"archived":{"type":"boolean"},"member_count":{"type":"integer"}},"required":["id","name","kind","parent_id","head","archived","member_count"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/units.create":{"post":{"operationId":"org.units.create","summary":"Create a unit","description":"Creates a division, department or team. parent_id defaults to the company root. Names are unique (case-insensitive). The kind \"company\" is reserved for the root.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"kind":{"type":"string","enum":["division","department","team"]},"parent_id":{"type":"string","minLength":1},"head_person_id":{"type":"string","minLength":1,"nullable":true}},"required":["name","kind"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["company","division","department","team"]},"parent_id":{"type":"string","nullable":true},"head":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"archived":{"type":"boolean"},"member_count":{"type":"integer"}},"required":["id","name","kind","parent_id","head","archived","member_count"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/units.update":{"post":{"operationId":"org.units.update","summary":"Rename, move or change a unit","description":"Updates a unit: name, kind, parent_id (moves the unit with its whole subtree) or head_person_id (the team lead; null clears it; see org_units_set_head — changing it changes no one's manager). A unit cannot move under itself or its own sub-units; the company root cannot move or change kind.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"unit_id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":100},"kind":{"type":"string","enum":["division","department","team"]},"parent_id":{"type":"string","minLength":1},"head_person_id":{"type":"string","minLength":1,"nullable":true}},"required":["unit_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["company","division","department","team"]},"parent_id":{"type":"string","nullable":true},"head":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"archived":{"type":"boolean"},"member_count":{"type":"integer"}},"required":["id","name","kind","parent_id","head","archived","member_count"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/units.set_head":{"post":{"operationId":"org.units.set_head","summary":"Set or remove the team lead of a unit","description":"Sets the team lead of a unit (the company, a division, department or team), effective now; person_id null removes the team lead. What a team lead means: people who join the unit later (hire, rehire, a job change into it, CSV import, org_setup_apply) get the lead as manager when no manager is given (the lead joining their own unit gets the parent unit's lead), and when Settings → Approval rules asks the manager to approve a change about someone with no manager, the lead of their unit (or of a unit above) decides before HR. Setting a lead changes no one's manager today: people already in the unit keep theirs. The lead must work here today or be starting later (people who have left are refused), and an archived unit cannot get a new lead. One person may lead several units. It never needs approval and the person keeps their own team. To also move the person into the unit, call org_people_change_job with unit_id and an explicit manager_id (that is a job change and follows Settings → Approval rules; without manager_id the unit's current lead would become their manager). Returns the unit, previous_head (who stopped being lead, or null), also_heads (other units this person already leads) and changed (false when that person was already the lead: nothing was written). Leads have no history: org_chart_get shows today's lead on any date. Owners, admins and HR only.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"unit_id":{"type":"string","minLength":1},"person_id":{"type":"string","minLength":1,"nullable":true,"description":"The new team lead (org_people_list), or null to remove the team lead."}},"required":["unit_id","person_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["company","division","department","team"]},"parent_id":{"type":"string","nullable":true},"head":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"archived":{"type":"boolean"},"member_count":{"type":"integer"},"previous_head":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"also_heads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"changed":{"type":"boolean"}},"required":["id","name","kind","parent_id","head","archived","member_count","previous_head","also_heads","changed"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/units.archive":{"post":{"operationId":"org.units.archive","summary":"Archive a unit","description":"Archives a unit that has no active sub-units. People already assigned keep the assignment, but nobody new can be assigned. The company root cannot be archived. Units are never deleted.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"unit_id":{"type":"string","minLength":1}},"required":["unit_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["company","division","department","team"]},"parent_id":{"type":"string","nullable":true},"head":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"archived":{"type":"boolean"},"member_count":{"type":"integer"}},"required":["id","name","kind","parent_id","head","archived","member_count"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/locations.list":{"post":{"operationId":"org.locations.list","summary":"List locations","description":"Lists offices and remote locations with country, city and time zone, oldest first. The first location sets the company time zone used for \"today\".","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"include_archived":{"type":"boolean","default":false,"description":"Also return archived items."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"},"city":{"type":"string","nullable":true},"timezone":{"type":"string"},"remote":{"type":"boolean"},"archived":{"type":"boolean"}},"required":["id","name","country","city","timezone","remote","archived"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.locations.list","summary":"List locations","description":"Lists offices and remote locations with country, city and time zone, oldest first. The first location sets the company time zone used for \"today\".","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"},"city":{"type":"string","nullable":true},"timezone":{"type":"string"},"remote":{"type":"boolean"},"archived":{"type":"boolean"}},"required":["id","name","country","city","timezone","remote","archived"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/locations.create":{"post":{"operationId":"org.locations.create","summary":"Create a location","description":"Creates a location. country is a 2-letter code; timezone defaults from the country (e.g. PT → Europe/Lisbon). Names are unique.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"country":{"allOf":[{"type":"string"},{"type":"string","pattern":"^[A-Z]{2}$"}]},"city":{"type":"string","maxLength":100,"nullable":true},"timezone":{"type":"string"},"remote":{"type":"boolean"}},"required":["name","country"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"},"city":{"type":"string","nullable":true},"timezone":{"type":"string"},"remote":{"type":"boolean"},"archived":{"type":"boolean"}},"required":["id","name","country","city","timezone","remote","archived"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/locations.update":{"post":{"operationId":"org.locations.update","summary":"Update a location","description":"Changes the name, country, city, time zone or remote flag of a location.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"location_id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":100},"country":{"allOf":[{"type":"string"},{"type":"string","pattern":"^[A-Z]{2}$"}]},"city":{"type":"string","maxLength":100,"nullable":true},"timezone":{"type":"string"},"remote":{"type":"boolean"}},"required":["location_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"},"city":{"type":"string","nullable":true},"timezone":{"type":"string"},"remote":{"type":"boolean"},"archived":{"type":"boolean"}},"required":["id","name","country","city","timezone","remote","archived"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/locations.archive":{"post":{"operationId":"org.locations.archive","summary":"Archive a location","description":"Archives a location: people keep it, but nobody new can be assigned to it. Locations are never deleted.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"location_id":{"type":"string","minLength":1}},"required":["location_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"},"city":{"type":"string","nullable":true},"timezone":{"type":"string"},"remote":{"type":"boolean"},"archived":{"type":"boolean"}},"required":["id","name","country","city","timezone","remote","archived"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/entities.list":{"post":{"operationId":"org.entities.list","summary":"List legal entities","description":"Lists the legal entities (employing companies) with country and tax id, oldest first.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"include_archived":{"type":"boolean","default":false,"description":"Also return archived items."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"legal_name":{"type":"string"},"country":{"type":"string"},"tax_id":{"type":"string","nullable":true},"archived":{"type":"boolean"}},"required":["id","legal_name","country","tax_id","archived"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.entities.list","summary":"List legal entities","description":"Lists the legal entities (employing companies) with country and tax id, oldest first.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"legal_name":{"type":"string"},"country":{"type":"string"},"tax_id":{"type":"string","nullable":true},"archived":{"type":"boolean"}},"required":["id","legal_name","country","tax_id","archived"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/entities.create":{"post":{"operationId":"org.entities.create","summary":"Create a legal entity","description":"Creates a legal entity (an employing company) with its 2-letter country and optional tax id.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"legal_name":{"type":"string","minLength":1,"maxLength":200},"country":{"allOf":[{"type":"string"},{"type":"string","pattern":"^[A-Z]{2}$"}]},"tax_id":{"type":"string","maxLength":40,"nullable":true}},"required":["legal_name","country"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"legal_name":{"type":"string"},"country":{"type":"string"},"tax_id":{"type":"string","nullable":true},"archived":{"type":"boolean"}},"required":["id","legal_name","country","tax_id","archived"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/entities.update":{"post":{"operationId":"org.entities.update","summary":"Update a legal entity","description":"Changes the legal name, country or tax id of a legal entity.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"legal_entity_id":{"type":"string","minLength":1},"legal_name":{"type":"string","minLength":1,"maxLength":200},"country":{"allOf":[{"type":"string"},{"type":"string","pattern":"^[A-Z]{2}$"}]},"tax_id":{"type":"string","maxLength":40,"nullable":true}},"required":["legal_entity_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"legal_name":{"type":"string"},"country":{"type":"string"},"tax_id":{"type":"string","nullable":true},"archived":{"type":"boolean"}},"required":["id","legal_name","country","tax_id","archived"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/entities.archive":{"post":{"operationId":"org.entities.archive","summary":"Archive a legal entity","description":"Archives a legal entity: existing job rows keep it, but nobody new can be assigned to it.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"legal_entity_id":{"type":"string","minLength":1}},"required":["legal_entity_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"legal_name":{"type":"string"},"country":{"type":"string"},"tax_id":{"type":"string","nullable":true},"archived":{"type":"boolean"}},"required":["id","legal_name","country","tax_id","archived"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/people.list":{"post":{"operationId":"org.people.list","summary":"List people (directory)","description":"Lists people as of a date (default: today in the company time zone), sorted by name. Returns public fields only (use org_people_get for one person). Filters combine (AND): status defaults to active + pre_hire (\"terminated\" or \"all\" include leavers; when joined_between or left_between is set it defaults to all); q searches name, email and title (case-insensitive); unit_id (ids from org_units_list; include_subunits=true adds every unit below it); location_id (org_locations_list); manager_id (a person id: their direct reports). HR filters (owners, admins and HR, in the app only; forbidden for others and over MCP or an API key, since they reveal job details): legal_entity_id (org_entities_list); joined_between {from, to} (YYYY-MM-DD, inclusive: an employment period, hire or rehire, starts in the range) and left_between {from, to} (the last day of an employment period falls in the range, including scheduled ones), counted as org_reports_headcount counts joiners and leavers. Unit, location, entity and manager are those of the job shown for the person as of the date (for leavers, their last job). A scheduled last day is job detail: with a future as_of, people whose job you cannot see still show as employed if they are today. Unknown ids are not_found. Erased people are never listed.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"as_of":{"type":"string"},"status":{"type":"string","enum":["active","pre_hire","terminated","all"]},"q":{"type":"string","maxLength":100},"unit_id":{"type":"string","minLength":1},"include_subunits":{"type":"boolean"},"location_id":{"type":"string","minLength":1},"legal_entity_id":{"type":"string","minLength":1},"manager_id":{"type":"string","minLength":1},"joined_between":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"left_between":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"given_name":{"type":"string"},"family_name":{"type":"string"},"preferred_name":{"type":"string","nullable":true},"work_email":{"type":"string"},"title":{"type":"string","nullable":true},"status":{"type":"string","enum":["pre_hire","active","terminated","none"]},"start_date":{"type":"string","nullable":true},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"invited":{"type":"boolean"},"has_login":{"type":"boolean"},"photo_url":{"type":"string","nullable":true}},"required":["id","name","given_name","family_name","preferred_name","work_email","title","status","start_date","unit","location","manager","invited","has_login","photo_url"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.people.list","summary":"List people (directory)","description":"Lists people as of a date (default: today in the company time zone), sorted by name. Returns public fields only (use org_people_get for one person). Filters combine (AND): status defaults to active + pre_hire (\"terminated\" or \"all\" include leavers; when joined_between or left_between is set it defaults to all); q searches name, email and title (case-insensitive); unit_id (ids from org_units_list; include_subunits=true adds every unit below it); location_id (org_locations_list); manager_id (a person id: their direct reports). HR filters (owners, admins and HR, in the app only; forbidden for others and over MCP or an API key, since they reveal job details): legal_entity_id (org_entities_list); joined_between {from, to} (YYYY-MM-DD, inclusive: an employment period, hire or rehire, starts in the range) and left_between {from, to} (the last day of an employment period falls in the range, including scheduled ones), counted as org_reports_headcount counts joiners and leavers. Unit, location, entity and manager are those of the job shown for the person as of the date (for leavers, their last job). A scheduled last day is job detail: with a future as_of, people whose job you cannot see still show as employed if they are today. Unknown ids are not_found. Erased people are never listed.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"given_name":{"type":"string"},"family_name":{"type":"string"},"preferred_name":{"type":"string","nullable":true},"work_email":{"type":"string"},"title":{"type":"string","nullable":true},"status":{"type":"string","enum":["pre_hire","active","terminated","none"]},"start_date":{"type":"string","nullable":true},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"invited":{"type":"boolean"},"has_login":{"type":"boolean"},"photo_url":{"type":"string","nullable":true}},"required":["id","name","given_name","family_name","preferred_name","work_email","title","status","start_date","unit","location","manager","invited","has_login","photo_url"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/people.get":{"post":{"operationId":"org.people.get","summary":"Get a person","description":"Returns one person as of a date: profile, current job, manager, direct reports and job history. Fields you may not see come back null; visible_tiers says which tiers (public, private, job, pay) you got; custom lists the custom fields you may see. Over MCP or an API key, private fields are only returned for yourself. Pay is separate: org_pay_list.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"person_id":{"type":"string","minLength":1},"as_of":{"type":"string"}},"required":["person_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"given_name":{"type":"string"},"family_name":{"type":"string"},"preferred_name":{"type":"string","nullable":true},"work_email":{"type":"string"},"title":{"type":"string","nullable":true},"status":{"type":"string","enum":["pre_hire","active","terminated","none"]},"start_date":{"type":"string","nullable":true},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"invited":{"type":"boolean"},"has_login":{"type":"boolean"},"photo_url":{"type":"string","nullable":true},"pronouns":{"type":"string","nullable":true},"work_phone":{"type":"string","nullable":true},"personal_email":{"type":"string","nullable":true},"personal_phone":{"type":"string","nullable":true},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["line1","city","country"],"additionalProperties":false,"nullable":true},"birthday":{"type":"string","nullable":true},"emergency_contacts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"relationship":{"type":"string"},"phone":{"type":"string"}},"required":["name","relationship","phone"],"additionalProperties":false},"nullable":true},"tax_id":{"type":"string","nullable":true},"social_security_number":{"type":"string","nullable":true},"iban":{"type":"string","nullable":true},"custom":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","date","select","boolean","file"]},"tier":{"type":"string","enum":["public","job","private"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"nullable":true,"description":"For type file: the document id (download it with documents_download or documents_me_download); over an API key or MCP, \"attached\" for someone else's file."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The file name; null over an API key or MCP for someone else's file."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false,"nullable":true,"description":"Type file only: the file, or null when none is attached."}},"required":["key","label","type","tier","value"],"additionalProperties":false}},"job":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"history":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false},"nullable":true},"reports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"visible_tiers":{"type":"array","items":{"type":"string","enum":["public","private","job","pay"]}}},"required":["id","name","given_name","family_name","preferred_name","work_email","title","status","start_date","unit","location","manager","invited","has_login","photo_url","pronouns","work_phone","personal_email","personal_phone","address","birthday","emergency_contacts","tax_id","social_security_number","iban","custom","job","history","reports","visible_tiers"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.people.get","summary":"Get a person","description":"Returns one person as of a date: profile, current job, manager, direct reports and job history. Fields you may not see come back null; visible_tiers says which tiers (public, private, job, pay) you got; custom lists the custom fields you may see. Over MCP or an API key, private fields are only returned for yourself. Pay is separate: org_pay_list.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"given_name":{"type":"string"},"family_name":{"type":"string"},"preferred_name":{"type":"string","nullable":true},"work_email":{"type":"string"},"title":{"type":"string","nullable":true},"status":{"type":"string","enum":["pre_hire","active","terminated","none"]},"start_date":{"type":"string","nullable":true},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"invited":{"type":"boolean"},"has_login":{"type":"boolean"},"photo_url":{"type":"string","nullable":true},"pronouns":{"type":"string","nullable":true},"work_phone":{"type":"string","nullable":true},"personal_email":{"type":"string","nullable":true},"personal_phone":{"type":"string","nullable":true},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["line1","city","country"],"additionalProperties":false,"nullable":true},"birthday":{"type":"string","nullable":true},"emergency_contacts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"relationship":{"type":"string"},"phone":{"type":"string"}},"required":["name","relationship","phone"],"additionalProperties":false},"nullable":true},"tax_id":{"type":"string","nullable":true},"social_security_number":{"type":"string","nullable":true},"iban":{"type":"string","nullable":true},"custom":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","date","select","boolean","file"]},"tier":{"type":"string","enum":["public","job","private"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"nullable":true,"description":"For type file: the document id (download it with documents_download or documents_me_download); over an API key or MCP, \"attached\" for someone else's file."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The file name; null over an API key or MCP for someone else's file."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false,"nullable":true,"description":"Type file only: the file, or null when none is attached."}},"required":["key","label","type","tier","value"],"additionalProperties":false}},"job":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"history":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false},"nullable":true},"reports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"visible_tiers":{"type":"array","items":{"type":"string","enum":["public","private","job","pay"]}}},"required":["id","name","given_name","family_name","preferred_name","work_email","title","status","start_date","unit","location","manager","invited","has_login","photo_url","pronouns","work_phone","personal_email","personal_phone","address","birthday","emergency_contacts","tax_id","social_security_number","iban","custom","job","history","reports","visible_tiers"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/people.hire":{"post":{"operationId":"org.people.hire","summary":"Hire (add) a person","description":"Adds a person with their first job. Required: given_name, family_name, work_email (unique), title, start_date (YYYY-MM-DD; a future date makes them pre_hire). Optional: unit_id, manager_id (must be employed or starting on start_date; when absent and unit_id is set, the team lead of that unit becomes the manager — manager_default in the result says so; send null for no manager; a position_id whose position names whom it reports to gets no default), location_id and legal_entity_id (default to the only active one), employment_type (full_time, part_time, contractor, intern; default full_time), fte (0–1, default 1), contract terms (contract_type: permanent, fixed_term, temporary, internship, freelance; contract_end_date for fixed_term/temporary/internship; probation_end_date; weekly_hours; notice_period_days), profile fields (including tax_id, social_security_number, iban) and custom: { <field key>: value } (see org_fields_list), position_id (an open or on-hold position from org_positions_list: the hire fills it, and positions that reported to it then report to the new person; drafts, filled and cancelled positions are refused). Starts the onboarding checklists that start by themselves and match the person (see org_checklists_runs_list), unless the start date is more than 30 days ago. Use dry_run first.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"given_name":{"type":"string","minLength":1,"maxLength":100},"family_name":{"type":"string","minLength":1,"maxLength":100},"work_email":{"allOf":[{"type":"string"},{"type":"string","format":"email","maxLength":254}]},"preferred_name":{"type":"string","minLength":1,"maxLength":100,"nullable":true},"pronouns":{"type":"string","maxLength":40,"nullable":true},"work_phone":{"type":"string","pattern":"^\\+?[0-9 ().-]{3,40}$","nullable":true},"personal_email":{"allOf":[{"type":"string"},{"type":"string","format":"email","maxLength":254}],"nullable":true},"personal_phone":{"type":"string","pattern":"^\\+?[0-9 ().-]{3,40}$","nullable":true},"address":{"type":"object","properties":{"line1":{"type":"string","minLength":1,"maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","minLength":1,"maxLength":100},"postal_code":{"type":"string","maxLength":20},"country":{"allOf":[{"type":"string"},{"type":"string","pattern":"^[A-Z]{2}$"}]}},"required":["line1","city","country"],"additionalProperties":false,"nullable":true},"birthday":{"type":"string","nullable":true},"emergency_contacts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"relationship":{"type":"string","minLength":1,"maxLength":60},"phone":{"type":"string","pattern":"^\\+?[0-9 ().-]{3,40}$"}},"required":["name","relationship","phone"],"additionalProperties":false},"maxItems":5},"tax_id":{"type":"string","pattern":"^[A-Za-z0-9 ./-]{1,40}$","nullable":true},"social_security_number":{"type":"string","pattern":"^[A-Za-z0-9 ./-]{1,40}$","nullable":true},"iban":{"allOf":[{"type":"string"},{"type":"string","pattern":"^[A-Z]{2}[0-9]{2}[A-Z0-9]{10,30}$"}],"nullable":true},"custom":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"}],"nullable":true}},"title":{"type":"string","minLength":1,"maxLength":120},"unit_id":{"type":"string","minLength":1,"nullable":true},"manager_id":{"type":"string","minLength":1,"nullable":true},"location_id":{"type":"string","minLength":1,"nullable":true},"legal_entity_id":{"type":"string","minLength":1,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"],"default":"full_time"},"fte":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":1,"default":1},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":80,"nullable":true},"notice_period_days":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"start_date":{"type":"string"},"position_id":{"type":"string","minLength":1}},"required":["given_name","family_name","work_email","title","start_date"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"given_name":{"type":"string"},"family_name":{"type":"string"},"preferred_name":{"type":"string","nullable":true},"work_email":{"type":"string"},"title":{"type":"string","nullable":true},"status":{"type":"string","enum":["pre_hire","active","terminated","none"]},"start_date":{"type":"string","nullable":true},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"invited":{"type":"boolean"},"has_login":{"type":"boolean"},"photo_url":{"type":"string","nullable":true},"pronouns":{"type":"string","nullable":true},"work_phone":{"type":"string","nullable":true},"personal_email":{"type":"string","nullable":true},"personal_phone":{"type":"string","nullable":true},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["line1","city","country"],"additionalProperties":false,"nullable":true},"birthday":{"type":"string","nullable":true},"emergency_contacts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"relationship":{"type":"string"},"phone":{"type":"string"}},"required":["name","relationship","phone"],"additionalProperties":false},"nullable":true},"tax_id":{"type":"string","nullable":true},"social_security_number":{"type":"string","nullable":true},"iban":{"type":"string","nullable":true},"custom":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","date","select","boolean","file"]},"tier":{"type":"string","enum":["public","job","private"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"nullable":true,"description":"For type file: the document id (download it with documents_download or documents_me_download); over an API key or MCP, \"attached\" for someone else's file."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The file name; null over an API key or MCP for someone else's file."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false,"nullable":true,"description":"Type file only: the file, or null when none is attached."}},"required":["key","label","type","tier","value"],"additionalProperties":false}},"job":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"history":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false},"nullable":true},"reports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"visible_tiers":{"type":"array","items":{"type":"string","enum":["public","private","job","pay"]}},"manager_default":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"}},"required":["unit_id","unit_name"],"additionalProperties":false,"description":"The manager was not given, so the lead of this team became the manager (null: the manager was given, or there was no default).","nullable":true}},"required":["id","name","given_name","family_name","preferred_name","work_email","title","status","start_date","unit","location","manager","invited","has_login","photo_url","pronouns","work_phone","personal_email","personal_phone","address","birthday","emergency_contacts","tax_id","social_security_number","iban","custom","job","history","reports","visible_tiers","manager_default"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/people.update_profile":{"post":{"operationId":"org.people.update_profile","summary":"Update a person's profile","description":"Changes profile fields of a person (names, work email, phones, personal email, address, birthday, pronouns, emergency contacts, tax_id, social_security_number, iban: payroll details change only in the app, never over MCP or an API key, and the person and every owner, admin and HR member are emailed when they change) and custom field values (custom: { <key>: value or null }, keys from org_fields_list). Send only the fields to change; null clears a field. Only owners and admins can change the work email of an owner's or admin's login. Job changes go through org_people_change_job.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"given_name":{"type":"string","minLength":1,"maxLength":100},"family_name":{"type":"string","minLength":1,"maxLength":100},"work_email":{"allOf":[{"type":"string"},{"type":"string","format":"email","maxLength":254}]},"preferred_name":{"type":"string","minLength":1,"maxLength":100,"nullable":true},"pronouns":{"type":"string","maxLength":40,"nullable":true},"work_phone":{"type":"string","pattern":"^\\+?[0-9 ().-]{3,40}$","nullable":true},"personal_email":{"allOf":[{"type":"string"},{"type":"string","format":"email","maxLength":254}],"nullable":true},"personal_phone":{"type":"string","pattern":"^\\+?[0-9 ().-]{3,40}$","nullable":true},"address":{"type":"object","properties":{"line1":{"type":"string","minLength":1,"maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","minLength":1,"maxLength":100},"postal_code":{"type":"string","maxLength":20},"country":{"allOf":[{"type":"string"},{"type":"string","pattern":"^[A-Z]{2}$"}]}},"required":["line1","city","country"],"additionalProperties":false,"nullable":true},"birthday":{"type":"string","nullable":true},"emergency_contacts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"relationship":{"type":"string","minLength":1,"maxLength":60},"phone":{"type":"string","pattern":"^\\+?[0-9 ().-]{3,40}$"}},"required":["name","relationship","phone"],"additionalProperties":false},"maxItems":5},"tax_id":{"type":"string","pattern":"^[A-Za-z0-9 ./-]{1,40}$","nullable":true},"social_security_number":{"type":"string","pattern":"^[A-Za-z0-9 ./-]{1,40}$","nullable":true},"iban":{"allOf":[{"type":"string"},{"type":"string","pattern":"^[A-Z]{2}[0-9]{2}[A-Z0-9]{10,30}$"}],"nullable":true},"custom":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"}],"nullable":true}},"person_id":{"type":"string","minLength":1}},"required":["person_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"given_name":{"type":"string"},"family_name":{"type":"string"},"preferred_name":{"type":"string","nullable":true},"work_email":{"type":"string"},"title":{"type":"string","nullable":true},"status":{"type":"string","enum":["pre_hire","active","terminated","none"]},"start_date":{"type":"string","nullable":true},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"invited":{"type":"boolean"},"has_login":{"type":"boolean"},"photo_url":{"type":"string","nullable":true},"pronouns":{"type":"string","nullable":true},"work_phone":{"type":"string","nullable":true},"personal_email":{"type":"string","nullable":true},"personal_phone":{"type":"string","nullable":true},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["line1","city","country"],"additionalProperties":false,"nullable":true},"birthday":{"type":"string","nullable":true},"emergency_contacts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"relationship":{"type":"string"},"phone":{"type":"string"}},"required":["name","relationship","phone"],"additionalProperties":false},"nullable":true},"tax_id":{"type":"string","nullable":true},"social_security_number":{"type":"string","nullable":true},"iban":{"type":"string","nullable":true},"custom":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","date","select","boolean","file"]},"tier":{"type":"string","enum":["public","job","private"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"nullable":true,"description":"For type file: the document id (download it with documents_download or documents_me_download); over an API key or MCP, \"attached\" for someone else's file."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The file name; null over an API key or MCP for someone else's file."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false,"nullable":true,"description":"Type file only: the file, or null when none is attached."}},"required":["key","label","type","tier","value"],"additionalProperties":false}},"job":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"history":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false},"nullable":true},"reports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"visible_tiers":{"type":"array","items":{"type":"string","enum":["public","private","job","pay"]}}},"required":["id","name","given_name","family_name","preferred_name","work_email","title","status","start_date","unit","location","manager","invited","has_login","photo_url","pronouns","work_phone","personal_email","personal_phone","address","birthday","emergency_contacts","tax_id","social_security_number","iban","custom","job","history","reports","visible_tiers"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/people.change_job":{"post":{"operationId":"org.people.change_job","summary":"Change a person's job (effective-dated)","description":"Records a job change from effective_date (YYYY-MM-DD, may be in the future): title, unit_id, manager_id, location_id, legal_entity_id, employment_type, fte and/or contract terms (contract_type, contract_end_date, probation_end_date, weekly_hours, notice_period_days; null clears one). reason is change, promotion or transfer. Moving into another unit without manager_id makes that unit's team lead the manager (the parent unit's lead when the person is that lead; manager_default in the result says so); send manager_id (or null) to choose. When Settings → Approval rules requires approval for job changes, nothing changes yet: a request is created for the approvers (approval in the result says who; org_approvals_get follows it) and the change applies when approved; a person can have one open job request at a time. The current row is closed on that date and a new one opens with the merged fields; a scheduled termination is kept. Rejected if the person is not employed that day, if a row already starts that day (use org_people_correct_job), if the manager is not employed then, or if it would create a reporting cycle on any day from effective_date on. Rows already scheduled after effective_date keep their own values — check history if a later change exists. If every field sent already has that value on effective_date, nothing is written and unchanged is true (safe to retry).","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"unit_id":{"type":"string","minLength":1,"nullable":true},"manager_id":{"type":"string","minLength":1,"nullable":true},"location_id":{"type":"string","minLength":1,"nullable":true},"legal_entity_id":{"type":"string","minLength":1,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":1},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":80,"nullable":true},"notice_period_days":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"person_id":{"type":"string","minLength":1},"effective_date":{"type":"string"},"reason":{"type":"string","enum":["change","promotion","transfer"]}},"required":["person_id","effective_date","reason"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"given_name":{"type":"string"},"family_name":{"type":"string"},"preferred_name":{"type":"string","nullable":true},"work_email":{"type":"string"},"title":{"type":"string","nullable":true},"status":{"type":"string","enum":["pre_hire","active","terminated","none"]},"start_date":{"type":"string","nullable":true},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"invited":{"type":"boolean"},"has_login":{"type":"boolean"},"photo_url":{"type":"string","nullable":true},"pronouns":{"type":"string","nullable":true},"work_phone":{"type":"string","nullable":true},"personal_email":{"type":"string","nullable":true},"personal_phone":{"type":"string","nullable":true},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["line1","city","country"],"additionalProperties":false,"nullable":true},"birthday":{"type":"string","nullable":true},"emergency_contacts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"relationship":{"type":"string"},"phone":{"type":"string"}},"required":["name","relationship","phone"],"additionalProperties":false},"nullable":true},"tax_id":{"type":"string","nullable":true},"social_security_number":{"type":"string","nullable":true},"iban":{"type":"string","nullable":true},"custom":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","date","select","boolean","file"]},"tier":{"type":"string","enum":["public","job","private"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"nullable":true,"description":"For type file: the document id (download it with documents_download or documents_me_download); over an API key or MCP, \"attached\" for someone else's file."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The file name; null over an API key or MCP for someone else's file."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false,"nullable":true,"description":"Type file only: the file, or null when none is attached."}},"required":["key","label","type","tier","value"],"additionalProperties":false}},"job":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"history":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false},"nullable":true},"reports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"visible_tiers":{"type":"array","items":{"type":"string","enum":["public","private","job","pay"]}},"approval":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","approved"]},"waiting_for":{"type":"string","enum":["manager","hr"],"nullable":true},"approvers":{"type":"array","items":{"type":"string"}},"automatic":{"type":"boolean"},"note":{"type":"string","enum":["proposed_by_approver","no_other_approver"],"nullable":true},"fallback":{"type":"boolean"},"team_lead":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"reason":{"type":"string","enum":["no_manager","manager_left"]}},"required":["unit_id","unit_name","reason"],"additionalProperties":false,"nullable":true},"team_lead_blocked":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"what":{"type":"string","enum":["lead","removed","moved","archived"]}},"required":["unit_id","unit_name","what"],"additionalProperties":false,"nullable":true},"untrusted":{"type":"string","enum":["no_login","invited_by_proposer"],"nullable":true},"then":{"type":"string","enum":["manager","hr"],"nullable":true}},"required":["id","status","waiting_for","approvers","automatic","note","fallback","team_lead","team_lead_blocked","untrusted","then"],"additionalProperties":false,"nullable":true},"unchanged":{"type":"boolean","description":"true when the job already was exactly so on effective_date: nothing was written."},"manager_default":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"}},"required":["unit_id","unit_name"],"additionalProperties":false,"description":"The manager was not given, so the lead of this team became the manager (null: the manager was given, or there was no default).","nullable":true}},"required":["id","name","given_name","family_name","preferred_name","work_email","title","status","start_date","unit","location","manager","invited","has_login","photo_url","pronouns","work_phone","personal_email","personal_phone","address","birthday","emergency_contacts","tax_id","social_security_number","iban","custom","job","history","reports","visible_tiers","approval","manager_default"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/people.terminate":{"post":{"operationId":"org.people.terminate","summary":"Terminate employment","description":"Ends employment after last_day (inclusive, YYYY-MM-DD, may be in the future) and starts the offboarding checklists that start by themselves (see org_checklists_runs_list); reason is free text (e.g. resigned; default: the reason of a scheduled termination it replaces, else \"terminated\"). Job changes scheduled after the last day are removed, and a later scheduled termination is moved to last_day. If this employment period already has an end date, use org_people_correct_job (valid_to = last day + 1) instead. Direct reports are NOT reassigned: warnings lists them so you can change their manager. If they have a login, warnings says so: it keeps working until an owner or admin disables it with platform_members_disable. When Settings → Approval rules requires approval for terminations, a request is created instead (approval in the result): the termination, and its offboarding checklists, start only when it is approved.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"person_id":{"type":"string","minLength":1},"last_day":{"type":"string"},"reason":{"type":"string","maxLength":200}},"required":["person_id","last_day"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"given_name":{"type":"string"},"family_name":{"type":"string"},"preferred_name":{"type":"string","nullable":true},"work_email":{"type":"string"},"title":{"type":"string","nullable":true},"status":{"type":"string","enum":["pre_hire","active","terminated","none"]},"start_date":{"type":"string","nullable":true},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"invited":{"type":"boolean"},"has_login":{"type":"boolean"},"photo_url":{"type":"string","nullable":true},"pronouns":{"type":"string","nullable":true},"work_phone":{"type":"string","nullable":true},"personal_email":{"type":"string","nullable":true},"personal_phone":{"type":"string","nullable":true},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["line1","city","country"],"additionalProperties":false,"nullable":true},"birthday":{"type":"string","nullable":true},"emergency_contacts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"relationship":{"type":"string"},"phone":{"type":"string"}},"required":["name","relationship","phone"],"additionalProperties":false},"nullable":true},"tax_id":{"type":"string","nullable":true},"social_security_number":{"type":"string","nullable":true},"iban":{"type":"string","nullable":true},"custom":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","date","select","boolean","file"]},"tier":{"type":"string","enum":["public","job","private"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"nullable":true,"description":"For type file: the document id (download it with documents_download or documents_me_download); over an API key or MCP, \"attached\" for someone else's file."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The file name; null over an API key or MCP for someone else's file."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false,"nullable":true,"description":"Type file only: the file, or null when none is attached."}},"required":["key","label","type","tier","value"],"additionalProperties":false}},"job":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"history":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false},"nullable":true},"reports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"visible_tiers":{"type":"array","items":{"type":"string","enum":["public","private","job","pay"]}}},"required":["id","name","given_name","family_name","preferred_name","work_email","title","status","start_date","unit","location","manager","invited","has_login","photo_url","pronouns","work_phone","personal_email","personal_phone","address","birthday","emergency_contacts","tax_id","social_security_number","iban","custom","job","history","reports","visible_tiers"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"}},"approval":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","approved"]},"waiting_for":{"type":"string","enum":["manager","hr"],"nullable":true},"approvers":{"type":"array","items":{"type":"string"}},"automatic":{"type":"boolean"},"note":{"type":"string","enum":["proposed_by_approver","no_other_approver"],"nullable":true},"fallback":{"type":"boolean"},"team_lead":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"reason":{"type":"string","enum":["no_manager","manager_left"]}},"required":["unit_id","unit_name","reason"],"additionalProperties":false,"nullable":true},"team_lead_blocked":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"what":{"type":"string","enum":["lead","removed","moved","archived"]}},"required":["unit_id","unit_name","what"],"additionalProperties":false,"nullable":true},"untrusted":{"type":"string","enum":["no_login","invited_by_proposer"],"nullable":true},"then":{"type":"string","enum":["manager","hr"],"nullable":true}},"required":["id","status","waiting_for","approvers","automatic","note","fallback","team_lead","team_lead_blocked","untrusted","then"],"additionalProperties":false,"nullable":true}},"required":["person","warnings","approval"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/people.rehire":{"post":{"operationId":"org.people.rehire","summary":"Rehire a former employee","description":"Starts a new employment for someone who has left, from start_date, with a new title and optional unit_id, manager_id (absent with a unit_id: that unit's team lead, as manager_default says; null for none), location_id, legal_entity_id, employment_type (default full_time) and fte (default 1). Rejected while they are still employed on start_date, if they already have a later job, or if they were never terminated (use org_people_hire for new people). When Settings → Approval rules requires approval for job changes, a request is created instead (approval in the result) and the rehire applies when approved.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"unit_id":{"type":"string","minLength":1,"nullable":true},"manager_id":{"type":"string","minLength":1,"nullable":true},"location_id":{"type":"string","minLength":1,"nullable":true},"legal_entity_id":{"type":"string","minLength":1,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"],"default":"full_time"},"fte":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":1,"default":1},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":80,"nullable":true},"notice_period_days":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"person_id":{"type":"string","minLength":1},"start_date":{"type":"string"}},"required":["title","person_id","start_date"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"given_name":{"type":"string"},"family_name":{"type":"string"},"preferred_name":{"type":"string","nullable":true},"work_email":{"type":"string"},"title":{"type":"string","nullable":true},"status":{"type":"string","enum":["pre_hire","active","terminated","none"]},"start_date":{"type":"string","nullable":true},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"invited":{"type":"boolean"},"has_login":{"type":"boolean"},"photo_url":{"type":"string","nullable":true},"pronouns":{"type":"string","nullable":true},"work_phone":{"type":"string","nullable":true},"personal_email":{"type":"string","nullable":true},"personal_phone":{"type":"string","nullable":true},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["line1","city","country"],"additionalProperties":false,"nullable":true},"birthday":{"type":"string","nullable":true},"emergency_contacts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"relationship":{"type":"string"},"phone":{"type":"string"}},"required":["name","relationship","phone"],"additionalProperties":false},"nullable":true},"tax_id":{"type":"string","nullable":true},"social_security_number":{"type":"string","nullable":true},"iban":{"type":"string","nullable":true},"custom":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","date","select","boolean","file"]},"tier":{"type":"string","enum":["public","job","private"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"nullable":true,"description":"For type file: the document id (download it with documents_download or documents_me_download); over an API key or MCP, \"attached\" for someone else's file."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The file name; null over an API key or MCP for someone else's file."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false,"nullable":true,"description":"Type file only: the file, or null when none is attached."}},"required":["key","label","type","tier","value"],"additionalProperties":false}},"job":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"history":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false},"nullable":true},"reports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"visible_tiers":{"type":"array","items":{"type":"string","enum":["public","private","job","pay"]}},"approval":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","approved"]},"waiting_for":{"type":"string","enum":["manager","hr"],"nullable":true},"approvers":{"type":"array","items":{"type":"string"}},"automatic":{"type":"boolean"},"note":{"type":"string","enum":["proposed_by_approver","no_other_approver"],"nullable":true},"fallback":{"type":"boolean"},"team_lead":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"reason":{"type":"string","enum":["no_manager","manager_left"]}},"required":["unit_id","unit_name","reason"],"additionalProperties":false,"nullable":true},"team_lead_blocked":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"what":{"type":"string","enum":["lead","removed","moved","archived"]}},"required":["unit_id","unit_name","what"],"additionalProperties":false,"nullable":true},"untrusted":{"type":"string","enum":["no_login","invited_by_proposer"],"nullable":true},"then":{"type":"string","enum":["manager","hr"],"nullable":true}},"required":["id","status","waiting_for","approvers","automatic","note","fallback","team_lead","team_lead_blocked","untrusted","then"],"additionalProperties":false,"nullable":true},"manager_default":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"}},"required":["unit_id","unit_name"],"additionalProperties":false,"description":"The manager was not given, so the lead of this team became the manager (null: the manager was given, or there was no default).","nullable":true}},"required":["id","name","given_name","family_name","preferred_name","work_email","title","status","start_date","unit","location","manager","invited","has_login","photo_url","pronouns","work_phone","personal_email","personal_phone","address","birthday","emergency_contacts","tax_id","social_security_number","iban","custom","job","history","reports","visible_tiers","approval","manager_default"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/people.correct_job":{"post":{"operationId":"org.people.correct_job","summary":"Correct a job row (fix history)","description":"Fixes a mistake in one job row in place, without recording a new change: title, unit_id, manager_id, location_id, legal_entity_id, employment_type, fte, or valid_from (a contiguous previous row is adjusted with it). On the last row of an employment period that already has an end date, valid_to (the day after the last day) and end_reason adjust the termination: a later valid_to postpones it, an earlier one moves it earlier within that row (to end before a scheduled change, use org_people_terminate), and valid_to = null cancels it. It never ends an open-ended row: use org_people_terminate for that. Use it for typos and wrong dates, not for real changes (use org_people_change_job). Open checklist tasks move with a corrected start date or last day, and cancelling a termination cancels its offboarding checklist. Every correction is audited. When Settings → Approval rules requires approval, a correction of the current or a future row (job changes), or of a last day (terminations), creates a request instead (approval in the result), and checklists move only when it is approved; corrections of rows that ended before today apply at once.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"unit_id":{"type":"string","minLength":1,"nullable":true},"manager_id":{"type":"string","minLength":1,"nullable":true},"location_id":{"type":"string","minLength":1,"nullable":true},"legal_entity_id":{"type":"string","minLength":1,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":1},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":80,"nullable":true},"notice_period_days":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"job_id":{"type":"string","minLength":1},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"end_reason":{"type":"string","maxLength":200,"nullable":true}},"required":["job_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"given_name":{"type":"string"},"family_name":{"type":"string"},"preferred_name":{"type":"string","nullable":true},"work_email":{"type":"string"},"title":{"type":"string","nullable":true},"status":{"type":"string","enum":["pre_hire","active","terminated","none"]},"start_date":{"type":"string","nullable":true},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"invited":{"type":"boolean"},"has_login":{"type":"boolean"},"photo_url":{"type":"string","nullable":true},"pronouns":{"type":"string","nullable":true},"work_phone":{"type":"string","nullable":true},"personal_email":{"type":"string","nullable":true},"personal_phone":{"type":"string","nullable":true},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["line1","city","country"],"additionalProperties":false,"nullable":true},"birthday":{"type":"string","nullable":true},"emergency_contacts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"relationship":{"type":"string"},"phone":{"type":"string"}},"required":["name","relationship","phone"],"additionalProperties":false},"nullable":true},"tax_id":{"type":"string","nullable":true},"social_security_number":{"type":"string","nullable":true},"iban":{"type":"string","nullable":true},"custom":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","date","select","boolean","file"]},"tier":{"type":"string","enum":["public","job","private"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"nullable":true,"description":"For type file: the document id (download it with documents_download or documents_me_download); over an API key or MCP, \"attached\" for someone else's file."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The file name; null over an API key or MCP for someone else's file."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false,"nullable":true,"description":"Type file only: the file, or null when none is attached."}},"required":["key","label","type","tier","value"],"additionalProperties":false}},"job":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"history":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false},"nullable":true},"reports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"visible_tiers":{"type":"array","items":{"type":"string","enum":["public","private","job","pay"]}},"approval":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","approved"]},"waiting_for":{"type":"string","enum":["manager","hr"],"nullable":true},"approvers":{"type":"array","items":{"type":"string"}},"automatic":{"type":"boolean"},"note":{"type":"string","enum":["proposed_by_approver","no_other_approver"],"nullable":true},"fallback":{"type":"boolean"},"team_lead":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"reason":{"type":"string","enum":["no_manager","manager_left"]}},"required":["unit_id","unit_name","reason"],"additionalProperties":false,"nullable":true},"team_lead_blocked":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"what":{"type":"string","enum":["lead","removed","moved","archived"]}},"required":["unit_id","unit_name","what"],"additionalProperties":false,"nullable":true},"untrusted":{"type":"string","enum":["no_login","invited_by_proposer"],"nullable":true},"then":{"type":"string","enum":["manager","hr"],"nullable":true}},"required":["id","status","waiting_for","approvers","automatic","note","fallback","team_lead","team_lead_blocked","untrusted","then"],"additionalProperties":false,"nullable":true}},"required":["id","name","given_name","family_name","preferred_name","work_email","title","status","start_date","unit","location","manager","invited","has_login","photo_url","pronouns","work_phone","personal_email","personal_phone","address","birthday","emergency_contacts","tax_id","social_security_number","iban","custom","job","history","reports","visible_tiers","approval"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/people.erase":{"post":{"operationId":"org.people.erase","summary":"Erase a former employee's personal data","description":"Anonymises a person whose employment has fully ended (every job row ended by today; none current or scheduled): names become 'Erased person', the work email becomes a placeholder, contact, private and custom fields and payroll identifiers are cleared, the profile photo, documents (with their files), pay history, reminder records, approval requests about them and their checklists (and their comments on others' tasks) are deleted, invite emails, email delivery records, webhook payloads sent about them and termination reasons are scrubbed. Job rows (dates, titles and contract terms) are kept, anonymised, for history; open invites are revoked and any login is disabled. Irreversible. Owners and admins only; you cannot erase yourself.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"person_id":{"type":"string","minLength":1}},"required":["person_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"person_id":{"type":"string"},"erased":{"type":"boolean","enum":[true]},"closed_requests":{"type":"integer"}},"required":["person_id","erased","closed_requests"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/me.get":{"post":{"operationId":"org.me.get","summary":"My profile","description":"Returns your own person record: profile (including private fields), current job, manager, reports and job history. Start here for anything about \"me\".","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"given_name":{"type":"string"},"family_name":{"type":"string"},"preferred_name":{"type":"string","nullable":true},"work_email":{"type":"string"},"title":{"type":"string","nullable":true},"status":{"type":"string","enum":["pre_hire","active","terminated","none"]},"start_date":{"type":"string","nullable":true},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"invited":{"type":"boolean"},"has_login":{"type":"boolean"},"photo_url":{"type":"string","nullable":true},"pronouns":{"type":"string","nullable":true},"work_phone":{"type":"string","nullable":true},"personal_email":{"type":"string","nullable":true},"personal_phone":{"type":"string","nullable":true},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["line1","city","country"],"additionalProperties":false,"nullable":true},"birthday":{"type":"string","nullable":true},"emergency_contacts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"relationship":{"type":"string"},"phone":{"type":"string"}},"required":["name","relationship","phone"],"additionalProperties":false},"nullable":true},"tax_id":{"type":"string","nullable":true},"social_security_number":{"type":"string","nullable":true},"iban":{"type":"string","nullable":true},"custom":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","date","select","boolean","file"]},"tier":{"type":"string","enum":["public","job","private"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"nullable":true,"description":"For type file: the document id (download it with documents_download or documents_me_download); over an API key or MCP, \"attached\" for someone else's file."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The file name; null over an API key or MCP for someone else's file."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false,"nullable":true,"description":"Type file only: the file, or null when none is attached."}},"required":["key","label","type","tier","value"],"additionalProperties":false}},"job":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"history":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false},"nullable":true},"reports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"visible_tiers":{"type":"array","items":{"type":"string","enum":["public","private","job","pay"]}}},"required":["id","name","given_name","family_name","preferred_name","work_email","title","status","start_date","unit","location","manager","invited","has_login","photo_url","pronouns","work_phone","personal_email","personal_phone","address","birthday","emergency_contacts","tax_id","social_security_number","iban","custom","job","history","reports","visible_tiers"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.me.get","summary":"My profile","description":"Returns your own person record: profile (including private fields), current job, manager, reports and job history. Start here for anything about \"me\".","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"given_name":{"type":"string"},"family_name":{"type":"string"},"preferred_name":{"type":"string","nullable":true},"work_email":{"type":"string"},"title":{"type":"string","nullable":true},"status":{"type":"string","enum":["pre_hire","active","terminated","none"]},"start_date":{"type":"string","nullable":true},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"invited":{"type":"boolean"},"has_login":{"type":"boolean"},"photo_url":{"type":"string","nullable":true},"pronouns":{"type":"string","nullable":true},"work_phone":{"type":"string","nullable":true},"personal_email":{"type":"string","nullable":true},"personal_phone":{"type":"string","nullable":true},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["line1","city","country"],"additionalProperties":false,"nullable":true},"birthday":{"type":"string","nullable":true},"emergency_contacts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"relationship":{"type":"string"},"phone":{"type":"string"}},"required":["name","relationship","phone"],"additionalProperties":false},"nullable":true},"tax_id":{"type":"string","nullable":true},"social_security_number":{"type":"string","nullable":true},"iban":{"type":"string","nullable":true},"custom":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","date","select","boolean","file"]},"tier":{"type":"string","enum":["public","job","private"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"nullable":true,"description":"For type file: the document id (download it with documents_download or documents_me_download); over an API key or MCP, \"attached\" for someone else's file."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The file name; null over an API key or MCP for someone else's file."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false,"nullable":true,"description":"Type file only: the file, or null when none is attached."}},"required":["key","label","type","tier","value"],"additionalProperties":false}},"job":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"history":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false},"nullable":true},"reports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"visible_tiers":{"type":"array","items":{"type":"string","enum":["public","private","job","pay"]}}},"required":["id","name","given_name","family_name","preferred_name","work_email","title","status","start_date","unit","location","manager","invited","has_login","photo_url","pronouns","work_phone","personal_email","personal_phone","address","birthday","emergency_contacts","tax_id","social_security_number","iban","custom","job","history","reports","visible_tiers"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/me.update":{"post":{"operationId":"org.me.update","summary":"Update my profile","description":"Updates your own self-editable fields: preferred_name, pronouns, work_phone, personal_email, personal_phone, address ({line1, line2?, city, postal_code?, country}), birthday (YYYY-MM-DD) and emergency_contacts (up to 5 of {name, relationship, phone}; the list replaces the old one). Payroll details (tax_id, social_security_number, iban) can only be changed by signing in to Bizisy, never over MCP or an API key. Send only what changes; null clears. Names, work email and job fields are changed by HR. Use dry_run first and confirm with the user.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"preferred_name":{"type":"string","minLength":1,"maxLength":100,"nullable":true},"pronouns":{"type":"string","maxLength":40,"nullable":true},"work_phone":{"type":"string","pattern":"^\\+?[0-9 ().-]{3,40}$","nullable":true},"personal_email":{"allOf":[{"type":"string"},{"type":"string","format":"email","maxLength":254}],"nullable":true},"personal_phone":{"type":"string","pattern":"^\\+?[0-9 ().-]{3,40}$","nullable":true},"address":{"type":"object","properties":{"line1":{"type":"string","minLength":1,"maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","minLength":1,"maxLength":100},"postal_code":{"type":"string","maxLength":20},"country":{"allOf":[{"type":"string"},{"type":"string","pattern":"^[A-Z]{2}$"}]}},"required":["line1","city","country"],"additionalProperties":false,"nullable":true},"birthday":{"type":"string","nullable":true},"emergency_contacts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"relationship":{"type":"string","minLength":1,"maxLength":60},"phone":{"type":"string","pattern":"^\\+?[0-9 ().-]{3,40}$"}},"required":["name","relationship","phone"],"additionalProperties":false},"maxItems":5},"tax_id":{"type":"string","pattern":"^[A-Za-z0-9 ./-]{1,40}$","nullable":true},"social_security_number":{"type":"string","pattern":"^[A-Za-z0-9 ./-]{1,40}$","nullable":true},"iban":{"allOf":[{"type":"string"},{"type":"string","pattern":"^[A-Z]{2}[0-9]{2}[A-Z0-9]{10,30}$"}],"nullable":true}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"given_name":{"type":"string"},"family_name":{"type":"string"},"preferred_name":{"type":"string","nullable":true},"work_email":{"type":"string"},"title":{"type":"string","nullable":true},"status":{"type":"string","enum":["pre_hire","active","terminated","none"]},"start_date":{"type":"string","nullable":true},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"invited":{"type":"boolean"},"has_login":{"type":"boolean"},"photo_url":{"type":"string","nullable":true},"pronouns":{"type":"string","nullable":true},"work_phone":{"type":"string","nullable":true},"personal_email":{"type":"string","nullable":true},"personal_phone":{"type":"string","nullable":true},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["line1","city","country"],"additionalProperties":false,"nullable":true},"birthday":{"type":"string","nullable":true},"emergency_contacts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"relationship":{"type":"string"},"phone":{"type":"string"}},"required":["name","relationship","phone"],"additionalProperties":false},"nullable":true},"tax_id":{"type":"string","nullable":true},"social_security_number":{"type":"string","nullable":true},"iban":{"type":"string","nullable":true},"custom":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","date","select","boolean","file"]},"tier":{"type":"string","enum":["public","job","private"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"nullable":true,"description":"For type file: the document id (download it with documents_download or documents_me_download); over an API key or MCP, \"attached\" for someone else's file."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The file name; null over an API key or MCP for someone else's file."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false,"nullable":true,"description":"Type file only: the file, or null when none is attached."}},"required":["key","label","type","tier","value"],"additionalProperties":false}},"job":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"history":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false},"nullable":true},"reports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"visible_tiers":{"type":"array","items":{"type":"string","enum":["public","private","job","pay"]}}},"required":["id","name","given_name","family_name","preferred_name","work_email","title","status","start_date","unit","location","manager","invited","has_login","photo_url","pronouns","work_phone","personal_email","personal_phone","address","birthday","emergency_contacts","tax_id","social_security_number","iban","custom","job","history","reports","visible_tiers"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/me.team":{"post":{"operationId":"org.me.team","summary":"My team","description":"Returns your manager, your peers (people with the same manager) and your direct reports, as of today.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"peers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"reports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}}},"required":["manager","peers","reports"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.me.team","summary":"My team","description":"Returns your manager, your peers (people with the same manager) and your direct reports, as of today.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"peers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"reports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}}},"required":["manager","peers","reports"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/chart.get":{"post":{"operationId":"org.chart.get","summary":"Org chart","description":"Returns the org chart as of a date (as_of, default today) as a flat list of nodes {id, kind, parent_id, label, sublabel, person_id?, photo_url?} (photo_url: path of the person photo on the company address, null without one). by=\"manager\" (default): one node per employed person under their manager. by=\"unit\": unit nodes (sublabel = kind) with people under their unit. Person nodes also carry unit_id, location_id, status (active or pre_hire), start_date (of the current employment period), is_unit_head (the current team lead of a live unit: team leads have no history, so this is today's value whatever as_of), direct_count and total_count (direct and all reports by manager among the people in this chart); unit nodes carry direct_count and total_count (people directly in the unit, and in it and every unit below). leaving_on (last day, when a termination is scheduled), contract_end (contract end date) and next_change {on, reason, title} (the next scheduled job change in the current employment, e.g. a promotion; null when none) appear only on people whose job details you may see, as in org_people_get (yourself, your reports, or everyone for owners, admins and HR, also over MCP or an API key); for anyone else a future as_of still shows people employed today whose last day falls before it. include_upcoming=true adds people starting within upcoming_days (default 30, at most 365) after the date, with status pre_hire. include_positions=true adds open roles: nodes of kind \"position\" (label = the position title) for the open and on-hold positions you may see (owners, admins and HR: all; a manager: those in their line; anyone else: none), with position_status, target_start_date, reason, unit_id and location_id; by manager they hang under the person or position they report to; when that person is not on the chart (starting later, or left) under the first of their managers who is, and under a role you cannot see, its first visible ancestor (else at the top), by unit under their unit (or the company). They are never counted in direct_count or total_count, and with an as_of before today there are none (positions are today's plan).","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"as_of":{"type":"string"},"by":{"type":"string","enum":["manager","unit"],"default":"manager"},"include_upcoming":{"type":"boolean","default":false},"upcoming_days":{"type":"integer","minimum":1,"maximum":365},"include_positions":{"type":"boolean","default":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["person","unit","position"]},"parent_id":{"type":"string","nullable":true},"label":{"type":"string"},"sublabel":{"type":"string","nullable":true},"person_id":{"type":"string"},"photo_url":{"type":"string","nullable":true},"unit_id":{"type":"string","nullable":true},"location_id":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","pre_hire"]},"start_date":{"type":"string","nullable":true},"is_unit_head":{"type":"boolean"},"direct_count":{"type":"integer"},"total_count":{"type":"integer"},"leaving_on":{"type":"string","nullable":true},"contract_end":{"type":"string","nullable":true},"next_change":{"type":"object","properties":{"on":{"type":"string"},"reason":{"type":"string"},"title":{"type":"string"}},"required":["on","reason","title"],"additionalProperties":false,"nullable":true},"position_status":{"type":"string","enum":["open","on_hold"]},"target_start_date":{"type":"string","nullable":true},"reason":{"type":"string","enum":["new","replacement"]}},"required":["id","kind","parent_id","label","sublabel"],"additionalProperties":false}}},"required":["nodes"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.chart.get","summary":"Org chart","description":"Returns the org chart as of a date (as_of, default today) as a flat list of nodes {id, kind, parent_id, label, sublabel, person_id?, photo_url?} (photo_url: path of the person photo on the company address, null without one). by=\"manager\" (default): one node per employed person under their manager. by=\"unit\": unit nodes (sublabel = kind) with people under their unit. Person nodes also carry unit_id, location_id, status (active or pre_hire), start_date (of the current employment period), is_unit_head (the current team lead of a live unit: team leads have no history, so this is today's value whatever as_of), direct_count and total_count (direct and all reports by manager among the people in this chart); unit nodes carry direct_count and total_count (people directly in the unit, and in it and every unit below). leaving_on (last day, when a termination is scheduled), contract_end (contract end date) and next_change {on, reason, title} (the next scheduled job change in the current employment, e.g. a promotion; null when none) appear only on people whose job details you may see, as in org_people_get (yourself, your reports, or everyone for owners, admins and HR, also over MCP or an API key); for anyone else a future as_of still shows people employed today whose last day falls before it. include_upcoming=true adds people starting within upcoming_days (default 30, at most 365) after the date, with status pre_hire. include_positions=true adds open roles: nodes of kind \"position\" (label = the position title) for the open and on-hold positions you may see (owners, admins and HR: all; a manager: those in their line; anyone else: none), with position_status, target_start_date, reason, unit_id and location_id; by manager they hang under the person or position they report to; when that person is not on the chart (starting later, or left) under the first of their managers who is, and under a role you cannot see, its first visible ancestor (else at the top), by unit under their unit (or the company). They are never counted in direct_count or total_count, and with an as_of before today there are none (positions are today's plan).","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["person","unit","position"]},"parent_id":{"type":"string","nullable":true},"label":{"type":"string"},"sublabel":{"type":"string","nullable":true},"person_id":{"type":"string"},"photo_url":{"type":"string","nullable":true},"unit_id":{"type":"string","nullable":true},"location_id":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","pre_hire"]},"start_date":{"type":"string","nullable":true},"is_unit_head":{"type":"boolean"},"direct_count":{"type":"integer"},"total_count":{"type":"integer"},"leaving_on":{"type":"string","nullable":true},"contract_end":{"type":"string","nullable":true},"next_change":{"type":"object","properties":{"on":{"type":"string"},"reason":{"type":"string"},"title":{"type":"string"}},"required":["on","reason","title"],"additionalProperties":false,"nullable":true},"position_status":{"type":"string","enum":["open","on_hold"]},"target_start_date":{"type":"string","nullable":true},"reason":{"type":"string","enum":["new","replacement"]}},"required":["id","kind","parent_id","label","sublabel"],"additionalProperties":false}}},"required":["nodes"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/chart.export":{"post":{"operationId":"org.chart.export","summary":"Export the org chart as a list","description":"Returns the org chart as a list, one row per person, in reporting order (each manager followed by the people under them): name, title, team, manager (name and manager_id), location, status (active, or pre_hire for people starting soon), start_date, level (1 = the top of the company), direct_reports and total_reports. format \"json\" (default) returns rows; format \"csv\" returns a CSV file (UTF-8, comma-separated; delimiter \";\" suits Excel in most of Europe; cells a spreadsheet would run as formulas are prefixed with '). Same people and dates as org_chart_get: as_of (default today), include_upcoming with upcoming_days (default 30, at most 365). Narrow it with root_person_id (that person and everyone under them; not_found if they are not on the chart on that date), unit_id (that team and its sub-teams; not_found for an unknown or archived team) and person_ids (only these people, at most 5000; ids not on the chart are ignored); filters combine. Everyone who can see the chart may use it, in the app, over MCP or with an API key. It never includes job details such as leaving dates, contract ends or scheduled changes, nor private or pay data. Pictures and PDFs of the chart are made in the Bizisy app (Org chart → Export).","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"as_of":{"type":"string"},"include_upcoming":{"type":"boolean","default":false},"upcoming_days":{"type":"integer","minimum":1,"maximum":365},"root_person_id":{"type":"string","minLength":1,"maxLength":100},"unit_id":{"type":"string","minLength":1,"maxLength":100},"person_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":5000},"format":{"type":"string","enum":["json","csv"],"default":"json"},"delimiter":{"type":"string","enum":[",",";"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"format":{"type":"string","enum":["json","csv"]},"filename":{"type":"string"},"as_of":{"type":"string"},"count":{"type":"integer"},"columns":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"type":"object","properties":{"person_id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"team":{"type":"string","nullable":true},"manager":{"type":"string","nullable":true},"manager_id":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","pre_hire"]},"start_date":{"type":"string","nullable":true},"level":{"type":"integer"},"direct_reports":{"type":"integer"},"total_reports":{"type":"integer"}},"required":["person_id","name","title","team","manager","manager_id","location","status","start_date","level","direct_reports","total_reports"],"additionalProperties":false}},"csv":{"type":"string"}},"required":["format","filename","as_of","count","columns"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.chart.export","summary":"Export the org chart as a list","description":"Returns the org chart as a list, one row per person, in reporting order (each manager followed by the people under them): name, title, team, manager (name and manager_id), location, status (active, or pre_hire for people starting soon), start_date, level (1 = the top of the company), direct_reports and total_reports. format \"json\" (default) returns rows; format \"csv\" returns a CSV file (UTF-8, comma-separated; delimiter \";\" suits Excel in most of Europe; cells a spreadsheet would run as formulas are prefixed with '). Same people and dates as org_chart_get: as_of (default today), include_upcoming with upcoming_days (default 30, at most 365). Narrow it with root_person_id (that person and everyone under them; not_found if they are not on the chart on that date), unit_id (that team and its sub-teams; not_found for an unknown or archived team) and person_ids (only these people, at most 5000; ids not on the chart are ignored); filters combine. Everyone who can see the chart may use it, in the app, over MCP or with an API key. It never includes job details such as leaving dates, contract ends or scheduled changes, nor private or pay data. Pictures and PDFs of the chart are made in the Bizisy app (Org chart → Export).","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"format":{"type":"string","enum":["json","csv"]},"filename":{"type":"string"},"as_of":{"type":"string"},"count":{"type":"integer"},"columns":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"type":"object","properties":{"person_id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"team":{"type":"string","nullable":true},"manager":{"type":"string","nullable":true},"manager_id":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","pre_hire"]},"start_date":{"type":"string","nullable":true},"level":{"type":"integer"},"direct_reports":{"type":"integer"},"total_reports":{"type":"integer"}},"required":["person_id","name","title","team","manager","manager_id","location","status","start_date","level","direct_reports","total_reports"],"additionalProperties":false}},"csv":{"type":"string"}},"required":["format","filename","as_of","count","columns"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/setup.apply":{"post":{"operationId":"org.setup.apply","summary":"Set up or update the company in bulk","description":"Creates or updates locations, units and people in one transaction (the fast path for setting up a whole company). At most 250 people per call: split bigger lists into batches. Matching: locations and units by name (case-insensitive), people by work_email; existing records are updated, missing ones created. People may also carry contract terms (contract_type, contract_end_date, probation_end_date, weekly_hours, notice_period_days), legal_entity (legal name), payroll details (tax_id, social_security_number, iban: refused over an API key or MCP; a change notifies the person and HR) and custom: { <field key>: value } (a file field takes no value here: upload files with documents_field_file_start; null removes one); pay is never set here (org_pay_add). A person's work_email is never changed here. units[].parent and people[].unit/location/manager_email may refer to items in the same payload, in any order. manager_email null says no manager (no default; an existing manager is cleared). A person joining or moving into a unit with no manager_email gets that unit's team lead as manager (team_lead_managers counts them; never a lead the same payload puts below them); people who stay in their unit keep their manager. Job changes of existing people take effect today (people hired today or not started yet are corrected in place); start dates of people already employed are not changed (a warning says so), nor are leavers. Everything is validated first; on validation_failed, details lists every problem with a path such as people[3].manager_email and nothing is written. Always call with dry_run=true first, show the counts and warnings to the user, and commit only after approval.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"locations":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"country":{"allOf":[{"type":"string"},{"type":"string","pattern":"^[A-Z]{2}$"}]},"city":{"type":"string","maxLength":100,"nullable":true},"timezone":{"type":"string"}},"required":["name","country"],"additionalProperties":false},"maxItems":50},"units":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"kind":{"type":"string","enum":["division","department","team"]},"parent":{"type":"string","minLength":1,"maxLength":100,"description":"Parent unit name; defaults to the company root for new units."}},"required":["name","kind"],"additionalProperties":false},"maxItems":200},"people":{"type":"array","items":{"type":"object","properties":{"given_name":{"type":"string","minLength":1,"maxLength":100},"family_name":{"type":"string","minLength":1,"maxLength":100},"work_email":{"allOf":[{"type":"string"},{"type":"string","format":"email","maxLength":254}]},"title":{"type":"string","minLength":1,"maxLength":120},"unit":{"type":"string","minLength":1,"maxLength":100},"manager_email":{"allOf":[{"type":"string"},{"type":"string","format":"email","maxLength":254}],"nullable":true,"description":"The manager's work email; null for no manager (no team-lead default); absent: the team lead for someone joining or moving teams, else unchanged."},"location":{"type":"string","minLength":1,"maxLength":100},"start_date":{"type":"string"},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"]},"contract_end_date":{"type":"string"},"probation_end_date":{"type":"string"},"weekly_hours":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":80},"notice_period_days":{"type":"integer","minimum":0,"maximum":365},"legal_entity":{"type":"string","minLength":1,"maxLength":200,"description":"Legal name of an existing legal entity (case-insensitive)."},"tax_id":{"type":"string","pattern":"^[A-Za-z0-9 ./-]{1,40}$"},"social_security_number":{"type":"string","pattern":"^[A-Za-z0-9 ./-]{1,40}$"},"iban":{"allOf":[{"type":"string"},{"type":"string","pattern":"^[A-Z]{2}[0-9]{2}[A-Z0-9]{10,30}$"}]},"custom":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"}],"nullable":true},"description":"Custom field values by key (org_fields_list); null clears one."}},"required":["given_name","family_name","work_email","title"],"additionalProperties":false},"description":"At most 250 people per call."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"created":{"type":"object","properties":{"locations":{"type":"integer"},"units":{"type":"integer"},"people":{"type":"integer"}},"required":["locations","units","people"],"additionalProperties":false},"updated":{"type":"object","properties":{"locations":{"type":"integer"},"units":{"type":"integer"},"people":{"type":"integer"}},"required":["locations","units","people"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"}},"team_lead_managers":{"type":"integer","description":"People who got their team lead as manager because no manager was given (new people, and people moving teams)."}},"required":["created","updated","warnings","team_lead_managers"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/people.import_csv":{"post":{"operationId":"org.people.import_csv","summary":"Import people from a CSV","description":"Imports people from CSV text (comma or semicolon separated, first row = header, at most 1 MB and 250 people; split bigger files into batches). Columns, any case: given_name, family_name, work_email, title (required), team, manager_email, location, start_date (YYYY-MM-DD), employment_type (full_time, part_time, contractor, intern), contract_type (permanent, fixed_term, temporary, internship, freelance), contract_end_date and probation_end_date (YYYY-MM-DD), weekly_hours (e.g. 40 or 37,5), notice_period_days, legal_entity (legal name of an existing entity), tax_id, social_security_number, iban (payroll details: only when signed in to Bizisy, refused over an API key or MCP), and custom fields by their key (org_fields_list; values typed per field, select values must be one of its options; private fields are refused over an API key or MCP). Empty cells leave values unchanged, except an empty manager_email for someone new or moving to another team: the team lead of that team becomes the manager (team_lead_managers counts them); write none (or -) in manager_email for no manager. Pay is never imported (record it with org_pay_add). Teams that do not exist yet become teams under the company root; locations and legal entities must already exist. Managers may appear anywhere in the file. Rows are matched by work_email like org_setup_apply. If row_errors is not empty, nothing was applied: fix those rows (row numbers as in a spreadsheet, the header is row 1; row 0 means the whole file) and retry. Unknown columns are ignored with a warning. Use dry_run first.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"csv":{"type":"string","minLength":1,"maxLength":1000000}},"required":["csv"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"created":{"type":"object","properties":{"locations":{"type":"integer"},"units":{"type":"integer"},"people":{"type":"integer"}},"required":["locations","units","people"],"additionalProperties":false},"updated":{"type":"object","properties":{"locations":{"type":"integer"},"units":{"type":"integer"},"people":{"type":"integer"}},"required":["locations","units","people"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"}},"team_lead_managers":{"type":"integer","description":"People who got their team lead as manager because no manager was given (new people, and people moving teams)."},"row_errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer"},"message":{"type":"string"}},"required":["row","message"],"additionalProperties":false}}},"required":["created","updated","warnings","team_lead_managers","row_errors"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/invites.create":{"post":{"operationId":"org.invites.create","summary":"Invite a person to sign in","description":"Creates a sign-in invite link for a person. role is member, viewer, hr or admin (hr and admin only for owners/admins); if the person already has a membership, omit role to keep theirs (a different role is a conflict: change it with platform_members_set_role). Bizisy emails the link to the person's work email (reply-to you); email.status says whether it was sent (email.reason rate_limited: the organization reached its daily email limit), and email.message says what to tell the user. Returns the link once as well, in the web app only: API keys and connected AI apps get url null (the link is a sign-in credential), so if email.status is not sent, tell the user to invite the person again from Bizisy and share the link privately. It expires in 14 days. Inviting again revokes their earlier open link. People who have left, or already have a login, cannot be invited.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"person_id":{"type":"string","minLength":1},"role":{"type":"string","enum":["member","hr","admin","viewer"]}},"required":["person_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"invite_id":{"type":"string"},"url":{"type":"string","nullable":true,"description":"The sign-in link, only for a person signed in to Bizisy; null for API keys and connected apps."},"expires_at":{"type":"string"},"email":{"type":"object","properties":{"status":{"type":"string","enum":["sent","failed","skipped"]},"message":{"type":"string"},"reason":{"type":"string","enum":["rate_limited"]}},"required":["status","message"],"additionalProperties":false}},"required":["invite_id","url","expires_at","email"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/invites.list":{"post":{"operationId":"org.invites.list","summary":"List invites","description":"Lists invites, newest first. By default only open ones (not accepted, revoked or expired); include_closed returns all. Filter by person_id. Links are never shown again: to resend, create a new invite.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"person_id":{"type":"string","minLength":1},"include_closed":{"type":"boolean","default":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"person_id":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"},"created_at":{"type":"string"},"expires_at":{"type":"string"},"accepted_at":{"type":"string","nullable":true},"revoked_at":{"type":"string","nullable":true}},"required":["id","person_id","email","role","created_at","expires_at","accepted_at","revoked_at"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.invites.list","summary":"List invites","description":"Lists invites, newest first. By default only open ones (not accepted, revoked or expired); include_closed returns all. Filter by person_id. Links are never shown again: to resend, create a new invite.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"person_id":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"},"created_at":{"type":"string"},"expires_at":{"type":"string"},"accepted_at":{"type":"string","nullable":true},"revoked_at":{"type":"string","nullable":true}},"required":["id","person_id","email","role","created_at","expires_at","accepted_at","revoked_at"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/invites.revoke":{"post":{"operationId":"org.invites.revoke","summary":"Revoke an invite","description":"Revokes an open invite so its link stops working; the login it would have created is removed. Accepted invites cannot be revoked (disable the member instead). Revoking an already revoked invite is a no-op.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"invite_id":{"type":"string","minLength":1}},"required":["invite_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"person_id":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"},"created_at":{"type":"string"},"expires_at":{"type":"string"},"accepted_at":{"type":"string","nullable":true},"revoked_at":{"type":"string","nullable":true}},"required":["id","person_id","email","role","created_at","expires_at","accepted_at","revoked_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/fields.list":{"post":{"operationId":"org.fields.list","summary":"List custom fields","description":"Lists the organization's custom person fields (key, label, type, options for select, tier, archived). Values live on each person (org_people_get → custom) and are set with org_people_update_profile or org_people_hire via custom: { <key>: value }. Tier decides who sees a field: public (everyone in the org), job (the person, their managers and HR) or private (the person and HR).","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"include_archived":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","date","select","boolean","file"]},"options":{"type":"array","items":{"type":"string"}},"tier":{"type":"string","enum":["public","job","private"]},"archived":{"type":"boolean"},"position":{"type":"integer"},"file":{"type":"object","properties":{"kinds":{"type":"array","items":{"type":"string","enum":["pdf","image","office"]},"description":"pdf (PDF), image (PNG, JPEG, WebP, HEIC), office (DOCX, XLSX, ODT, ODS)."},"max_mb":{"type":"integer","nullable":true,"description":"The field's largest file in MB; null = the company's limit. The smaller of the two applies."},"self_upload":{"type":"boolean","description":"People upload their own file in Bizisy Me (it counts toward their monthly self-upload limit)."}},"required":["kinds","max_mb","self_upload"],"additionalProperties":false,"nullable":true,"description":"Type file only; null for other types."}},"required":["id","key","label","type","options","tier","archived","position","file"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.fields.list","summary":"List custom fields","description":"Lists the organization's custom person fields (key, label, type, options for select, tier, archived). Values live on each person (org_people_get → custom) and are set with org_people_update_profile or org_people_hire via custom: { <key>: value }. Tier decides who sees a field: public (everyone in the org), job (the person, their managers and HR) or private (the person and HR).","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","date","select","boolean","file"]},"options":{"type":"array","items":{"type":"string"}},"tier":{"type":"string","enum":["public","job","private"]},"archived":{"type":"boolean"},"position":{"type":"integer"},"file":{"type":"object","properties":{"kinds":{"type":"array","items":{"type":"string","enum":["pdf","image","office"]},"description":"pdf (PDF), image (PNG, JPEG, WebP, HEIC), office (DOCX, XLSX, ODT, ODS)."},"max_mb":{"type":"integer","nullable":true,"description":"The field's largest file in MB; null = the company's limit. The smaller of the two applies."},"self_upload":{"type":"boolean","description":"People upload their own file in Bizisy Me (it counts toward their monthly self-upload limit)."}},"required":["kinds","max_mb","self_upload"],"additionalProperties":false,"nullable":true,"description":"Type file only; null for other types."}},"required":["id","key","label","type","options","tier","archived","position","file"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/fields.create":{"post":{"operationId":"org.fields.create","summary":"Add a custom field","description":"Adds a custom person field. label (shown in the app), type (text, number, date, select, boolean, file), options (2–50, select only), tier (public, job or private; default private). key defaults to the label in snake_case and never changes. File fields hold one file per person (a document: it also shows in the person's Documents, from the field) and take file: { kinds (pdf, image, office; default all), max_mb (1–100 or null for the company's largest-file limit; the smaller applies), self_upload (default false: people upload their own in Bizisy Me, counted toward their monthly self-upload limit) }; their files follow the field's tier. At most 30 active fields.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":60},"type":{"type":"string","enum":["text","number","date","select","boolean","file"]},"options":{"type":"array","items":{"type":"string","minLength":1,"maxLength":80},"minItems":2,"maxItems":50},"tier":{"type":"string","enum":["public","job","private"],"default":"private"},"key":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"file":{"type":"object","properties":{"kinds":{"type":"array","items":{"type":"string","enum":["pdf","image","office"]},"minItems":1,"maxItems":10},"max_mb":{"type":"integer","minimum":1,"maximum":100,"nullable":true},"self_upload":{"type":"boolean"}},"additionalProperties":false}},"required":["label","type"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","date","select","boolean","file"]},"options":{"type":"array","items":{"type":"string"}},"tier":{"type":"string","enum":["public","job","private"]},"archived":{"type":"boolean"},"position":{"type":"integer"},"file":{"type":"object","properties":{"kinds":{"type":"array","items":{"type":"string","enum":["pdf","image","office"]},"description":"pdf (PDF), image (PNG, JPEG, WebP, HEIC), office (DOCX, XLSX, ODT, ODS)."},"max_mb":{"type":"integer","nullable":true,"description":"The field's largest file in MB; null = the company's limit. The smaller of the two applies."},"self_upload":{"type":"boolean","description":"People upload their own file in Bizisy Me (it counts toward their monthly self-upload limit)."}},"required":["kinds","max_mb","self_upload"],"additionalProperties":false,"nullable":true,"description":"Type file only; null for other types."}},"required":["id","key","label","type","options","tier","archived","position","file"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/fields.update":{"post":{"operationId":"org.fields.update","summary":"Change a custom field","description":"Changes a custom field: label, tier, options (select only; removing an option some people still have is refused), file options (file only: kinds, max_mb, self_upload; they apply to new uploads, files already attached stay), position, or archived (archived fields are hidden from forms; their values are kept and included in personal-data exports, not in the people CSV). The key and type never change. Widening the tier (private to job or public, job to public) while people have values would show those values to more people: it is refused unless confirm_expose_existing is true, which is accepted only in the app, after the user confirmed.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"field_id":{"type":"string","minLength":1},"label":{"type":"string","minLength":1,"maxLength":60},"tier":{"type":"string","enum":["public","job","private"]},"options":{"type":"array","items":{"type":"string","minLength":1,"maxLength":80},"minItems":2,"maxItems":50},"position":{"type":"integer","minimum":0,"maximum":1000},"archived":{"type":"boolean"},"file":{"type":"object","properties":{"kinds":{"type":"array","items":{"type":"string","enum":["pdf","image","office"]},"minItems":1,"maxItems":10},"max_mb":{"type":"integer","minimum":1,"maximum":100,"nullable":true},"self_upload":{"type":"boolean"}},"additionalProperties":false},"confirm_expose_existing":{"type":"boolean"}},"required":["field_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","date","select","boolean","file"]},"options":{"type":"array","items":{"type":"string"}},"tier":{"type":"string","enum":["public","job","private"]},"archived":{"type":"boolean"},"position":{"type":"integer"},"file":{"type":"object","properties":{"kinds":{"type":"array","items":{"type":"string","enum":["pdf","image","office"]},"description":"pdf (PDF), image (PNG, JPEG, WebP, HEIC), office (DOCX, XLSX, ODT, ODS)."},"max_mb":{"type":"integer","nullable":true,"description":"The field's largest file in MB; null = the company's limit. The smaller of the two applies."},"self_upload":{"type":"boolean","description":"People upload their own file in Bizisy Me (it counts toward their monthly self-upload limit)."}},"required":["kinds","max_mb","self_upload"],"additionalProperties":false,"nullable":true,"description":"Type file only; null for other types."},"previous_tier":{"type":"string","enum":["public","job","private"]}},"required":["id","key","label","type","options","tier","archived","position","file","previous_tier"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/pay.list":{"post":{"operationId":"org.pay.list","summary":"List a person's pay","description":"Returns a person's pay history (amount, currency, period: year, month or hour; effective from valid_from until the next row) and the row in force today. Visible to the person themselves and to owners, admins and HR in the app; managers never see pay. Over MCP or an API key, pay is only returned for yourself.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"person_id":{"type":"string","minLength":1}},"required":["person_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"person_id":{"type":"string"},"current":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","valid_from","valid_to","amount","currency","period","note","created_at"],"additionalProperties":false,"nullable":true},"history":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","valid_from","valid_to","amount","currency","period","note","created_at"],"additionalProperties":false}},"payroll_changed_at":{"type":"string","nullable":true}},"required":["person_id","current","history","payroll_changed_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.pay.list","summary":"List a person's pay","description":"Returns a person's pay history (amount, currency, period: year, month or hour; effective from valid_from until the next row) and the row in force today. Visible to the person themselves and to owners, admins and HR in the app; managers never see pay. Over MCP or an API key, pay is only returned for yourself.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"person_id":{"type":"string"},"current":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","valid_from","valid_to","amount","currency","period","note","created_at"],"additionalProperties":false,"nullable":true},"history":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","valid_from","valid_to","amount","currency","period","note","created_at"],"additionalProperties":false}},"payroll_changed_at":{"type":"string","nullable":true}},"required":["person_id","current","history","payroll_changed_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/pay.add":{"post":{"operationId":"org.pay.add","summary":"Record a pay change","description":"Records pay from effective_date (YYYY-MM-DD, may be in the future): amount (gross, at most 2 decimals), currency (ISO code, e.g. EUR), period (year, month or hour) and an optional note. It applies until the next recorded change. One row per date: a second change on the same date is refused (remove the wrong one with org_pay_remove first). Only in the app (never over MCP or an API key), by owners, admins and HR, never for their own pay; an HR member's pay only by an owner or admin, an owner's only by another owner. When Settings → Approval rules requires HR approval for pay changes, a request is created instead (approval in the result) and the pay applies when another owner, admin or HR member approves it.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"person_id":{"type":"string","minLength":1},"effective_date":{"type":"string"},"amount":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":100000000},"currency":{"allOf":[{"type":"string"},{"type":"string","pattern":"^[A-Z]{3}$"}]},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","maxLength":200}},"required":["person_id","effective_date","amount","currency","period"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"person_id":{"type":"string"},"current":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","valid_from","valid_to","amount","currency","period","note","created_at"],"additionalProperties":false,"nullable":true},"history":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","valid_from","valid_to","amount","currency","period","note","created_at"],"additionalProperties":false}},"payroll_changed_at":{"type":"string","nullable":true},"approval":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","approved"]},"waiting_for":{"type":"string","enum":["manager","hr"],"nullable":true},"approvers":{"type":"array","items":{"type":"string"}},"automatic":{"type":"boolean"},"note":{"type":"string","enum":["proposed_by_approver","no_other_approver"],"nullable":true},"fallback":{"type":"boolean"},"team_lead":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"reason":{"type":"string","enum":["no_manager","manager_left"]}},"required":["unit_id","unit_name","reason"],"additionalProperties":false,"nullable":true},"team_lead_blocked":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"what":{"type":"string","enum":["lead","removed","moved","archived"]}},"required":["unit_id","unit_name","what"],"additionalProperties":false,"nullable":true},"untrusted":{"type":"string","enum":["no_login","invited_by_proposer"],"nullable":true},"then":{"type":"string","enum":["manager","hr"],"nullable":true}},"required":["id","status","waiting_for","approvers","automatic","note","fallback","team_lead","team_lead_blocked","untrusted","then"],"additionalProperties":false,"nullable":true}},"required":["person_id","current","history","payroll_changed_at","approval"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/pay.remove":{"post":{"operationId":"org.pay.remove","summary":"Remove a pay row (fix a mistake)","description":"Deletes one pay row recorded by mistake (pay_id from org_pay_list); the previous row then applies until the next one. Same rules as org_pay_add: in the app only, never your own pay. When Settings → Approval rules requires HR approval for pay changes, removing the row in force today or a scheduled one creates a request instead (approval in the result); removing an older row applies at once.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pay_id":{"type":"string","minLength":1}},"required":["pay_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"person_id":{"type":"string"},"current":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","valid_from","valid_to","amount","currency","period","note","created_at"],"additionalProperties":false,"nullable":true},"history":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","valid_from","valid_to","amount","currency","period","note","created_at"],"additionalProperties":false}},"payroll_changed_at":{"type":"string","nullable":true},"approval":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","approved"]},"waiting_for":{"type":"string","enum":["manager","hr"],"nullable":true},"approvers":{"type":"array","items":{"type":"string"}},"automatic":{"type":"boolean"},"note":{"type":"string","enum":["proposed_by_approver","no_other_approver"],"nullable":true},"fallback":{"type":"boolean"},"team_lead":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"reason":{"type":"string","enum":["no_manager","manager_left"]}},"required":["unit_id","unit_name","reason"],"additionalProperties":false,"nullable":true},"team_lead_blocked":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"what":{"type":"string","enum":["lead","removed","moved","archived"]}},"required":["unit_id","unit_name","what"],"additionalProperties":false,"nullable":true},"untrusted":{"type":"string","enum":["no_login","invited_by_proposer"],"nullable":true},"then":{"type":"string","enum":["manager","hr"],"nullable":true}},"required":["id","status","waiting_for","approvers","automatic","note","fallback","team_lead","team_lead_blocked","untrusted","then"],"additionalProperties":false,"nullable":true}},"required":["person_id","current","history","payroll_changed_at","approval"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/people.export_csv":{"post":{"operationId":"org.people.export_csv","summary":"Export people as CSV","description":"Exports people as a CSV file (UTF-8, comma-separated by default; delimiter \";\" suits Excel in most of Europe; one row per person) as of a date: names, work email and phone, status, start date, current job (title, team, manager, location, legal entity, employment type, FTE, contract terms) and active custom fields (archived fields are left out; personal-data exports include them). status defaults to active + pre_hire (\"all\" includes leavers). include_private adds personal contact details, birthday, address, tax id, social security number, IBAN and private custom fields: owners, admins and HR in the app only, never over MCP or an API key. Pay is not included.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"as_of":{"type":"string"},"status":{"type":"string","enum":["active","pre_hire","terminated","all"]},"include_private":{"type":"boolean"},"delimiter":{"type":"string","enum":[",",";"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"filename":{"type":"string"},"csv":{"type":"string"},"rows":{"type":"integer"},"columns":{"type":"array","items":{"type":"string"}}},"required":["filename","csv","rows","columns"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.people.export_csv","summary":"Export people as CSV","description":"Exports people as a CSV file (UTF-8, comma-separated by default; delimiter \";\" suits Excel in most of Europe; one row per person) as of a date: names, work email and phone, status, start date, current job (title, team, manager, location, legal entity, employment type, FTE, contract terms) and active custom fields (archived fields are left out; personal-data exports include them). status defaults to active + pre_hire (\"all\" includes leavers). include_private adds personal contact details, birthday, address, tax id, social security number, IBAN and private custom fields: owners, admins and HR in the app only, never over MCP or an API key. Pay is not included.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"filename":{"type":"string"},"csv":{"type":"string"},"rows":{"type":"integer"},"columns":{"type":"array","items":{"type":"string"}}},"required":["filename","csv","rows","columns"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/people.export_data":{"post":{"operationId":"org.people.export_data","summary":"Export a person's data (GDPR access request)","description":"Returns everything Bizisy holds about one person in this organization as JSON, to answer a data access request: profile (all fields, including private and custom), the profile photo (base64), every document of the person (metadata, plus document_files: 5-minute download links the web app puts in one zip), job history, pay history, invites, their logins (email, role, sign-in methods), their API keys (names and dates, never secrets), their Activity, open positions they filled or are recorded as replaced in, change requests about them (approvals), their checklists (about them, assigned to them, and their comments) and webhook deliveries about them in the last 30 days. Owners, admins and HR, in the app only: it contains private data, so over MCP or an API key it only works for yourself (or use org_me_export_data).","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"person_id":{"type":"string","minLength":1}},"required":["person_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"format":{"type":"string","enum":["bizisy.person-data.v1"]},"generated_at":{"type":"string"},"organization_id":{"type":"string"},"person":{"type":"object","additionalProperties":{}},"photo":{"type":"object","properties":{"content_type":{"type":"string"},"data_base64":{"type":"string"},"updated_at":{"type":"string"}},"required":["content_type","data_base64","updated_at"],"additionalProperties":false,"nullable":true},"jobs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false}},"pay":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","valid_from","valid_to","amount","currency","period","note","created_at"],"additionalProperties":false}},"invites":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"role":{"type":"string"},"created_at":{"type":"string"},"expires_at":{"type":"string"},"accepted_at":{"type":"string","nullable":true},"revoked_at":{"type":"string","nullable":true}},"required":["email","role","created_at","expires_at","accepted_at","revoked_at"],"additionalProperties":false}},"logins":{"type":"array","items":{"type":"object","additionalProperties":{}}},"api_keys":{"type":"array","items":{"type":"object","additionalProperties":{}}},"connected_apps":{"type":"array","items":{"type":"object","additionalProperties":{}}},"activity":{"type":"array","items":{"type":"object","additionalProperties":{}}},"activity_truncated":{"type":"boolean"},"notifications":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"created_at":{"type":"string"},"read_at":{"type":"string","nullable":true}},"required":["type","created_at","read_at"],"additionalProperties":false}},"reminders":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"date":{"type":"string"},"sent_at":{"type":"string"}},"required":["kind","date","sent_at"],"additionalProperties":false}},"positions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"role":{"type":"string","enum":["filled","replaced"]}},"required":["id","title","status","role"],"additionalProperties":false}},"approvals":{"type":"array","items":{"type":"object","additionalProperties":{}}},"checklists":{"type":"object","properties":{"about_you":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string"},"anchor_date":{"type":"string"},"started_at":{"type":"string"},"tasks":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"due_date":{"type":"string"},"status":{"type":"string"},"skip_reason":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true},"comments":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"at":{"type":"string"},"by_you":{"type":"boolean"}},"required":["text","at","by_you"],"additionalProperties":false}}},"required":["title","due_date","status","skip_reason","resolved_at","comments"],"additionalProperties":false}}},"required":["name","kind","status","anchor_date","started_at","tasks"],"additionalProperties":false}},"assigned_to_you":{"type":"array","items":{"type":"object","properties":{"checklist":{"type":"string"},"title":{"type":"string"},"due_date":{"type":"string"},"status":{"type":"string"},"resolved_at":{"type":"string","nullable":true}},"required":["checklist","title","due_date","status","resolved_at"],"additionalProperties":false}},"your_comments":{"type":"array","items":{"type":"object","properties":{"checklist":{"type":"string"},"task":{"type":"string"},"text":{"type":"string"},"at":{"type":"string"}},"required":["checklist","task","text","at"],"additionalProperties":false}},"resolved_by_you":{"type":"array","items":{"type":"object","properties":{"checklist":{"type":"string"},"task":{"type":"string"},"status":{"type":"string"},"skip_reason":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true}},"required":["checklist","task","status","skip_reason","resolved_at"],"additionalProperties":false}},"template_tasks":{"type":"array","items":{"type":"object","properties":{"template":{"type":"string"},"task":{"type":"string"}},"required":["template","task"],"additionalProperties":false}}},"required":["about_you","assigned_to_you","your_comments","resolved_by_you","template_tasks"],"additionalProperties":false},"webhook_deliveries":{"type":"array","items":{"type":"object","properties":{"event_type":{"type":"string"},"endpoint_host":{"type":"string"},"created_at":{"type":"string"},"status":{"type":"string"}},"required":["event_type","endpoint_host","created_at","status"],"additionalProperties":false}},"documents":{"type":"array","items":{"type":"object","additionalProperties":{}}},"document_files":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"additionalProperties":false}},"filename":{"type":"string"}},"required":["format","generated_at","organization_id","person","photo","jobs","pay","invites","logins","api_keys","connected_apps","activity","activity_truncated","notifications","reminders","positions","approvals","checklists","webhook_deliveries","documents","document_files","filename"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.people.export_data","summary":"Export a person's data (GDPR access request)","description":"Returns everything Bizisy holds about one person in this organization as JSON, to answer a data access request: profile (all fields, including private and custom), the profile photo (base64), every document of the person (metadata, plus document_files: 5-minute download links the web app puts in one zip), job history, pay history, invites, their logins (email, role, sign-in methods), their API keys (names and dates, never secrets), their Activity, open positions they filled or are recorded as replaced in, change requests about them (approvals), their checklists (about them, assigned to them, and their comments) and webhook deliveries about them in the last 30 days. Owners, admins and HR, in the app only: it contains private data, so over MCP or an API key it only works for yourself (or use org_me_export_data).","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"format":{"type":"string","enum":["bizisy.person-data.v1"]},"generated_at":{"type":"string"},"organization_id":{"type":"string"},"person":{"type":"object","additionalProperties":{}},"photo":{"type":"object","properties":{"content_type":{"type":"string"},"data_base64":{"type":"string"},"updated_at":{"type":"string"}},"required":["content_type","data_base64","updated_at"],"additionalProperties":false,"nullable":true},"jobs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false}},"pay":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","valid_from","valid_to","amount","currency","period","note","created_at"],"additionalProperties":false}},"invites":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"role":{"type":"string"},"created_at":{"type":"string"},"expires_at":{"type":"string"},"accepted_at":{"type":"string","nullable":true},"revoked_at":{"type":"string","nullable":true}},"required":["email","role","created_at","expires_at","accepted_at","revoked_at"],"additionalProperties":false}},"logins":{"type":"array","items":{"type":"object","additionalProperties":{}}},"api_keys":{"type":"array","items":{"type":"object","additionalProperties":{}}},"connected_apps":{"type":"array","items":{"type":"object","additionalProperties":{}}},"activity":{"type":"array","items":{"type":"object","additionalProperties":{}}},"activity_truncated":{"type":"boolean"},"notifications":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"created_at":{"type":"string"},"read_at":{"type":"string","nullable":true}},"required":["type","created_at","read_at"],"additionalProperties":false}},"reminders":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"date":{"type":"string"},"sent_at":{"type":"string"}},"required":["kind","date","sent_at"],"additionalProperties":false}},"positions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"role":{"type":"string","enum":["filled","replaced"]}},"required":["id","title","status","role"],"additionalProperties":false}},"approvals":{"type":"array","items":{"type":"object","additionalProperties":{}}},"checklists":{"type":"object","properties":{"about_you":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string"},"anchor_date":{"type":"string"},"started_at":{"type":"string"},"tasks":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"due_date":{"type":"string"},"status":{"type":"string"},"skip_reason":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true},"comments":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"at":{"type":"string"},"by_you":{"type":"boolean"}},"required":["text","at","by_you"],"additionalProperties":false}}},"required":["title","due_date","status","skip_reason","resolved_at","comments"],"additionalProperties":false}}},"required":["name","kind","status","anchor_date","started_at","tasks"],"additionalProperties":false}},"assigned_to_you":{"type":"array","items":{"type":"object","properties":{"checklist":{"type":"string"},"title":{"type":"string"},"due_date":{"type":"string"},"status":{"type":"string"},"resolved_at":{"type":"string","nullable":true}},"required":["checklist","title","due_date","status","resolved_at"],"additionalProperties":false}},"your_comments":{"type":"array","items":{"type":"object","properties":{"checklist":{"type":"string"},"task":{"type":"string"},"text":{"type":"string"},"at":{"type":"string"}},"required":["checklist","task","text","at"],"additionalProperties":false}},"resolved_by_you":{"type":"array","items":{"type":"object","properties":{"checklist":{"type":"string"},"task":{"type":"string"},"status":{"type":"string"},"skip_reason":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true}},"required":["checklist","task","status","skip_reason","resolved_at"],"additionalProperties":false}},"template_tasks":{"type":"array","items":{"type":"object","properties":{"template":{"type":"string"},"task":{"type":"string"}},"required":["template","task"],"additionalProperties":false}}},"required":["about_you","assigned_to_you","your_comments","resolved_by_you","template_tasks"],"additionalProperties":false},"webhook_deliveries":{"type":"array","items":{"type":"object","properties":{"event_type":{"type":"string"},"endpoint_host":{"type":"string"},"created_at":{"type":"string"},"status":{"type":"string"}},"required":["event_type","endpoint_host","created_at","status"],"additionalProperties":false}},"documents":{"type":"array","items":{"type":"object","additionalProperties":{}}},"document_files":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"additionalProperties":false}},"filename":{"type":"string"}},"required":["format","generated_at","organization_id","person","photo","jobs","pay","invites","logins","api_keys","connected_apps","activity","activity_truncated","notifications","reminders","positions","approvals","checklists","webhook_deliveries","documents","document_files","filename"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/me.export_data":{"post":{"operationId":"org.me.export_data","summary":"Export my data","description":"Returns everything Bizisy holds about you in this organization as JSON (your right of access): profile, profile photo (base64), the documents shared with you (metadata, plus document_files: 5-minute download links), job history, pay history, invites, your logins, API keys (names and dates, never secrets), your Activity, open positions you filled or are recorded as replaced in (those you may see), decided change requests about you (approvals), your checklists (about you, tasks assigned to you, and your comments) and webhook deliveries about you in the last 30 days.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"format":{"type":"string","enum":["bizisy.person-data.v1"]},"generated_at":{"type":"string"},"organization_id":{"type":"string"},"person":{"type":"object","additionalProperties":{}},"photo":{"type":"object","properties":{"content_type":{"type":"string"},"data_base64":{"type":"string"},"updated_at":{"type":"string"}},"required":["content_type","data_base64","updated_at"],"additionalProperties":false,"nullable":true},"jobs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false}},"pay":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","valid_from","valid_to","amount","currency","period","note","created_at"],"additionalProperties":false}},"invites":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"role":{"type":"string"},"created_at":{"type":"string"},"expires_at":{"type":"string"},"accepted_at":{"type":"string","nullable":true},"revoked_at":{"type":"string","nullable":true}},"required":["email","role","created_at","expires_at","accepted_at","revoked_at"],"additionalProperties":false}},"logins":{"type":"array","items":{"type":"object","additionalProperties":{}}},"api_keys":{"type":"array","items":{"type":"object","additionalProperties":{}}},"connected_apps":{"type":"array","items":{"type":"object","additionalProperties":{}}},"activity":{"type":"array","items":{"type":"object","additionalProperties":{}}},"activity_truncated":{"type":"boolean"},"notifications":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"created_at":{"type":"string"},"read_at":{"type":"string","nullable":true}},"required":["type","created_at","read_at"],"additionalProperties":false}},"reminders":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"date":{"type":"string"},"sent_at":{"type":"string"}},"required":["kind","date","sent_at"],"additionalProperties":false}},"positions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"role":{"type":"string","enum":["filled","replaced"]}},"required":["id","title","status","role"],"additionalProperties":false}},"approvals":{"type":"array","items":{"type":"object","additionalProperties":{}}},"checklists":{"type":"object","properties":{"about_you":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string"},"anchor_date":{"type":"string"},"started_at":{"type":"string"},"tasks":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"due_date":{"type":"string"},"status":{"type":"string"},"skip_reason":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true},"comments":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"at":{"type":"string"},"by_you":{"type":"boolean"}},"required":["text","at","by_you"],"additionalProperties":false}}},"required":["title","due_date","status","skip_reason","resolved_at","comments"],"additionalProperties":false}}},"required":["name","kind","status","anchor_date","started_at","tasks"],"additionalProperties":false}},"assigned_to_you":{"type":"array","items":{"type":"object","properties":{"checklist":{"type":"string"},"title":{"type":"string"},"due_date":{"type":"string"},"status":{"type":"string"},"resolved_at":{"type":"string","nullable":true}},"required":["checklist","title","due_date","status","resolved_at"],"additionalProperties":false}},"your_comments":{"type":"array","items":{"type":"object","properties":{"checklist":{"type":"string"},"task":{"type":"string"},"text":{"type":"string"},"at":{"type":"string"}},"required":["checklist","task","text","at"],"additionalProperties":false}},"resolved_by_you":{"type":"array","items":{"type":"object","properties":{"checklist":{"type":"string"},"task":{"type":"string"},"status":{"type":"string"},"skip_reason":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true}},"required":["checklist","task","status","skip_reason","resolved_at"],"additionalProperties":false}},"template_tasks":{"type":"array","items":{"type":"object","properties":{"template":{"type":"string"},"task":{"type":"string"}},"required":["template","task"],"additionalProperties":false}}},"required":["about_you","assigned_to_you","your_comments","resolved_by_you","template_tasks"],"additionalProperties":false},"webhook_deliveries":{"type":"array","items":{"type":"object","properties":{"event_type":{"type":"string"},"endpoint_host":{"type":"string"},"created_at":{"type":"string"},"status":{"type":"string"}},"required":["event_type","endpoint_host","created_at","status"],"additionalProperties":false}},"documents":{"type":"array","items":{"type":"object","additionalProperties":{}}},"document_files":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"additionalProperties":false}},"filename":{"type":"string"}},"required":["format","generated_at","organization_id","person","photo","jobs","pay","invites","logins","api_keys","connected_apps","activity","activity_truncated","notifications","reminders","positions","approvals","checklists","webhook_deliveries","documents","document_files","filename"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.me.export_data","summary":"Export my data","description":"Returns everything Bizisy holds about you in this organization as JSON (your right of access): profile, profile photo (base64), the documents shared with you (metadata, plus document_files: 5-minute download links), job history, pay history, invites, your logins, API keys (names and dates, never secrets), your Activity, open positions you filled or are recorded as replaced in (those you may see), decided change requests about you (approvals), your checklists (about you, tasks assigned to you, and your comments) and webhook deliveries about you in the last 30 days.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"format":{"type":"string","enum":["bizisy.person-data.v1"]},"generated_at":{"type":"string"},"organization_id":{"type":"string"},"person":{"type":"object","additionalProperties":{}},"photo":{"type":"object","properties":{"content_type":{"type":"string"},"data_base64":{"type":"string"},"updated_at":{"type":"string"}},"required":["content_type","data_base64","updated_at"],"additionalProperties":false,"nullable":true},"jobs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false}},"pay":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","valid_from","valid_to","amount","currency","period","note","created_at"],"additionalProperties":false}},"invites":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"role":{"type":"string"},"created_at":{"type":"string"},"expires_at":{"type":"string"},"accepted_at":{"type":"string","nullable":true},"revoked_at":{"type":"string","nullable":true}},"required":["email","role","created_at","expires_at","accepted_at","revoked_at"],"additionalProperties":false}},"logins":{"type":"array","items":{"type":"object","additionalProperties":{}}},"api_keys":{"type":"array","items":{"type":"object","additionalProperties":{}}},"connected_apps":{"type":"array","items":{"type":"object","additionalProperties":{}}},"activity":{"type":"array","items":{"type":"object","additionalProperties":{}}},"activity_truncated":{"type":"boolean"},"notifications":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"created_at":{"type":"string"},"read_at":{"type":"string","nullable":true}},"required":["type","created_at","read_at"],"additionalProperties":false}},"reminders":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"date":{"type":"string"},"sent_at":{"type":"string"}},"required":["kind","date","sent_at"],"additionalProperties":false}},"positions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"role":{"type":"string","enum":["filled","replaced"]}},"required":["id","title","status","role"],"additionalProperties":false}},"approvals":{"type":"array","items":{"type":"object","additionalProperties":{}}},"checklists":{"type":"object","properties":{"about_you":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string"},"anchor_date":{"type":"string"},"started_at":{"type":"string"},"tasks":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"due_date":{"type":"string"},"status":{"type":"string"},"skip_reason":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true},"comments":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"at":{"type":"string"},"by_you":{"type":"boolean"}},"required":["text","at","by_you"],"additionalProperties":false}}},"required":["title","due_date","status","skip_reason","resolved_at","comments"],"additionalProperties":false}}},"required":["name","kind","status","anchor_date","started_at","tasks"],"additionalProperties":false}},"assigned_to_you":{"type":"array","items":{"type":"object","properties":{"checklist":{"type":"string"},"title":{"type":"string"},"due_date":{"type":"string"},"status":{"type":"string"},"resolved_at":{"type":"string","nullable":true}},"required":["checklist","title","due_date","status","resolved_at"],"additionalProperties":false}},"your_comments":{"type":"array","items":{"type":"object","properties":{"checklist":{"type":"string"},"task":{"type":"string"},"text":{"type":"string"},"at":{"type":"string"}},"required":["checklist","task","text","at"],"additionalProperties":false}},"resolved_by_you":{"type":"array","items":{"type":"object","properties":{"checklist":{"type":"string"},"task":{"type":"string"},"status":{"type":"string"},"skip_reason":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true}},"required":["checklist","task","status","skip_reason","resolved_at"],"additionalProperties":false}},"template_tasks":{"type":"array","items":{"type":"object","properties":{"template":{"type":"string"},"task":{"type":"string"}},"required":["template","task"],"additionalProperties":false}}},"required":["about_you","assigned_to_you","your_comments","resolved_by_you","template_tasks"],"additionalProperties":false},"webhook_deliveries":{"type":"array","items":{"type":"object","properties":{"event_type":{"type":"string"},"endpoint_host":{"type":"string"},"created_at":{"type":"string"},"status":{"type":"string"}},"required":["event_type","endpoint_host","created_at","status"],"additionalProperties":false}},"documents":{"type":"array","items":{"type":"object","additionalProperties":{}}},"document_files":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"additionalProperties":false}},"filename":{"type":"string"}},"required":["format","generated_at","organization_id","person","photo","jobs","pay","invites","logins","api_keys","connected_apps","activity","activity_truncated","notifications","reminders","positions","approvals","checklists","webhook_deliveries","documents","document_files","filename"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/reports.headcount":{"post":{"operationId":"org.reports.headcount","summary":"Headcount report","description":"Monthly workforce numbers from the job history, from from_month to to_month (YYYY-MM, at most 36 months; default the last 12 months): headcount on the first and last day, FTE at month end, joiners (employment periods starting that month, rehires included), leavers (last day that month) and turnover_rate (leavers / average headcount; null when the average is under one person). The current month is counted as of today. breakdown counts people employed at the end of to_month (or today, if that is earlier), grouped by group_by: unit (default), location, legal_entity, employment_type or contract_type. totals sums the period. planned (when the report reaches today; else null): headcount employed today, open = positions with status open (not drafts or on-hold ones), planned = headcount + open; each breakdown row then also has open, the open positions in that group (null when grouped by employment_type, which positions do not have), and a group with only open positions gets a row with count 0. To list the people behind a number: each month's range (the days counted; the current month ends today) as org_people_list joined_between or left_between; a breakdown group as org_people_list with unit_id, location_id or legal_entity_id, as_of = as_of and status \"active\" (erased people are counted, anonymously, up to the day before their erase, but never listed). Owners, admins and HR.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from_month":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"to_month":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"group_by":{"type":"string","enum":["unit","location","legal_entity","employment_type","contract_type"],"default":"unit"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"from_month":{"type":"string"},"to_month":{"type":"string"},"group_by":{"type":"string","enum":["unit","location","legal_entity","employment_type","contract_type"]},"as_of":{"type":"string"},"months":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string"},"headcount_start":{"type":"integer"},"headcount_end":{"type":"integer"},"fte_end":{"type":"number"},"joiners":{"type":"integer"},"leavers":{"type":"integer"},"turnover_rate":{"type":"number","nullable":true},"range":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false}},"required":["month","headcount_start","headcount_end","fte_end","joiners","leavers","turnover_rate","range"],"additionalProperties":false}},"breakdown":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","nullable":true},"label":{"type":"string"},"count":{"type":"integer"},"fte":{"type":"number"},"open":{"type":"integer","nullable":true}},"required":["key","label","count","fte","open"],"additionalProperties":false}},"planned":{"type":"object","properties":{"headcount":{"type":"integer"},"open":{"type":"integer"},"planned":{"type":"integer"}},"required":["headcount","open","planned"],"additionalProperties":false,"nullable":true},"totals":{"type":"object","properties":{"joiners":{"type":"integer"},"leavers":{"type":"integer"},"turnover_rate":{"type":"number","nullable":true}},"required":["joiners","leavers","turnover_rate"],"additionalProperties":false}},"required":["from_month","to_month","group_by","as_of","months","breakdown","planned","totals"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.reports.headcount","summary":"Headcount report","description":"Monthly workforce numbers from the job history, from from_month to to_month (YYYY-MM, at most 36 months; default the last 12 months): headcount on the first and last day, FTE at month end, joiners (employment periods starting that month, rehires included), leavers (last day that month) and turnover_rate (leavers / average headcount; null when the average is under one person). The current month is counted as of today. breakdown counts people employed at the end of to_month (or today, if that is earlier), grouped by group_by: unit (default), location, legal_entity, employment_type or contract_type. totals sums the period. planned (when the report reaches today; else null): headcount employed today, open = positions with status open (not drafts or on-hold ones), planned = headcount + open; each breakdown row then also has open, the open positions in that group (null when grouped by employment_type, which positions do not have), and a group with only open positions gets a row with count 0. To list the people behind a number: each month's range (the days counted; the current month ends today) as org_people_list joined_between or left_between; a breakdown group as org_people_list with unit_id, location_id or legal_entity_id, as_of = as_of and status \"active\" (erased people are counted, anonymously, up to the day before their erase, but never listed). Owners, admins and HR.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"from_month":{"type":"string"},"to_month":{"type":"string"},"group_by":{"type":"string","enum":["unit","location","legal_entity","employment_type","contract_type"]},"as_of":{"type":"string"},"months":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string"},"headcount_start":{"type":"integer"},"headcount_end":{"type":"integer"},"fte_end":{"type":"number"},"joiners":{"type":"integer"},"leavers":{"type":"integer"},"turnover_rate":{"type":"number","nullable":true},"range":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false}},"required":["month","headcount_start","headcount_end","fte_end","joiners","leavers","turnover_rate","range"],"additionalProperties":false}},"breakdown":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","nullable":true},"label":{"type":"string"},"count":{"type":"integer"},"fte":{"type":"number"},"open":{"type":"integer","nullable":true}},"required":["key","label","count","fte","open"],"additionalProperties":false}},"planned":{"type":"object","properties":{"headcount":{"type":"integer"},"open":{"type":"integer"},"planned":{"type":"integer"}},"required":["headcount","open","planned"],"additionalProperties":false,"nullable":true},"totals":{"type":"object","properties":{"joiners":{"type":"integer"},"leavers":{"type":"integer"},"turnover_rate":{"type":"number","nullable":true}},"required":["joiners","leavers","turnover_rate"],"additionalProperties":false}},"required":["from_month","to_month","group_by","as_of","months","breakdown","planned","totals"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/home.summary":{"post":{"operationId":"org.home.summary","summary":"Home summary (what needs attention)","description":"What needs an HR person's attention today, as on Bizisy's Manage Home. headcount: people employed today and month-end headcount for the last 12 months (this month as of today). joining_this_month: employment periods starting this month. leaving_soon: last days in the next 60 days. invites: pending (open) invites of current people, and current people with neither a login nor an invite. needs: approvals (count of change requests waiting for your decision, which you approve in Bizisy; always first), first_day (someone starting within 60 days who has not been invited), probation_ends (within 60 days), offboard (last day within 60 days; count = people still reporting to them after it), move_roles (open roles that report to someone leaving or gone: count and position ids; move them with org_positions_update), no_manager (people hired into an open role who still have no manager: count and person ids), contract_ends (fixed-term and similar contracts ending within 90 days), invite_people (count and person ids), unit_heads (units without a team lead: count and unit ids), personal_details (how many current people have no emergency contact or home address; app only). Dated items come first, by date. coming: the next 60 days of starts, last days, probation and contract ends and scheduled job changes. positions: how many open positions are open, on hold and draft, and how many open ones are past their target start date (list them with org_positions_list). checklists: open onboarding, offboarding and custom checklists with their progress (done, skipped, total) and how many open tasks are overdue. tasks: your own checklist tasks (HR tasks included) due within 7 days or overdue; tick them with org_checklists_tasks_set_status. Other items disappear when the data changes; there is no done or snooze. Names and titles are public; job details follow the usual job tier; no private or pay data. Owners, admins and HR.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"as_of":{"type":"string"},"headcount":{"type":"object","properties":{"now":{"type":"integer"},"months":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string"},"headcount":{"type":"integer"}},"required":["month","headcount"],"additionalProperties":false}}},"required":["now","months"],"additionalProperties":false},"joining_this_month":{"type":"array","items":{"type":"object","properties":{"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"date":{"type":"string"}},"required":["person","date"],"additionalProperties":false}},"leaving_soon":{"type":"array","items":{"type":"object","properties":{"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"date":{"type":"string"}},"required":["person","date"],"additionalProperties":false}},"invites":{"type":"object","properties":{"pending":{"type":"integer"},"not_invited":{"type":"integer"}},"required":["pending","not_invited"],"additionalProperties":false},"needs":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["approvals","first_day","probation_ends","offboard","move_roles","contract_ends","invite_people","unit_heads","personal_details","no_manager"]},"date":{"type":"string","nullable":true},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"count":{"type":"integer","nullable":true},"ids":{"type":"array","items":{"type":"string"}},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true}},"required":["kind","date","person","manager","count","ids","contract_type"],"additionalProperties":false}},"coming":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["starts","last_day","probation_ends","contract_ends","job_change"]},"date":{"type":"string"},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"reason":{"type":"string","nullable":true},"title":{"type":"string","nullable":true}},"required":["kind","date","person","reason","title"],"additionalProperties":false}},"positions":{"type":"object","properties":{"open":{"type":"integer"},"on_hold":{"type":"integer"},"draft":{"type":"integer"},"past_target":{"type":"integer"}},"required":["open","on_hold","draft","past_target"],"additionalProperties":false},"checklists":{"type":"object","properties":{"open":{"type":"integer"},"overdue_tasks":{"type":"integer"},"runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"anchor_date":{"type":"string"},"progress":{"type":"object","properties":{"done":{"type":"integer"},"skipped":{"type":"integer"},"total":{"type":"integer"}},"required":["done","skipped","total"],"additionalProperties":false}},"required":["id","name","kind","person","anchor_date","progress"],"additionalProperties":false}}},"required":["open","overdue_tasks","runs"],"additionalProperties":false},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"link_url":{"type":"string","nullable":true},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true}},"required":["type","person"],"additionalProperties":false},"manager_missing":{"type":"boolean"},"offset_days":{"type":"integer"},"due_date":{"type":"string"},"visible_from":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","done","skipped"]},"resolved_at":{"type":"string","nullable":true},"resolved_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"skip_reason":{"type":"string","nullable":true},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"text":{"type":"string"},"at":{"type":"string"}},"required":["id","author","text","at"],"additionalProperties":false}},"can":{"type":"object","properties":{"tick":{"type":"boolean"},"skip":{"type":"boolean"},"reassign":{"type":"boolean"},"comment":{"type":"boolean"}},"required":["tick","skip","reassign","comment"],"additionalProperties":false},"run":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"status":{"type":"string","enum":["open","completed","cancelled"]},"anchor_date":{"type":"string","nullable":true}},"required":["id","name","kind","status","anchor_date"],"additionalProperties":false},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"required":["id","title","description","link_url","assignee","manager_missing","offset_days","due_date","visible_from","status","resolved_at","resolved_by","skip_reason","comments","can","run","person"],"additionalProperties":false}}},"required":["as_of","headcount","joining_this_month","leaving_soon","invites","needs","coming","positions","checklists","tasks"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.home.summary","summary":"Home summary (what needs attention)","description":"What needs an HR person's attention today, as on Bizisy's Manage Home. headcount: people employed today and month-end headcount for the last 12 months (this month as of today). joining_this_month: employment periods starting this month. leaving_soon: last days in the next 60 days. invites: pending (open) invites of current people, and current people with neither a login nor an invite. needs: approvals (count of change requests waiting for your decision, which you approve in Bizisy; always first), first_day (someone starting within 60 days who has not been invited), probation_ends (within 60 days), offboard (last day within 60 days; count = people still reporting to them after it), move_roles (open roles that report to someone leaving or gone: count and position ids; move them with org_positions_update), no_manager (people hired into an open role who still have no manager: count and person ids), contract_ends (fixed-term and similar contracts ending within 90 days), invite_people (count and person ids), unit_heads (units without a team lead: count and unit ids), personal_details (how many current people have no emergency contact or home address; app only). Dated items come first, by date. coming: the next 60 days of starts, last days, probation and contract ends and scheduled job changes. positions: how many open positions are open, on hold and draft, and how many open ones are past their target start date (list them with org_positions_list). checklists: open onboarding, offboarding and custom checklists with their progress (done, skipped, total) and how many open tasks are overdue. tasks: your own checklist tasks (HR tasks included) due within 7 days or overdue; tick them with org_checklists_tasks_set_status. Other items disappear when the data changes; there is no done or snooze. Names and titles are public; job details follow the usual job tier; no private or pay data. Owners, admins and HR.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"as_of":{"type":"string"},"headcount":{"type":"object","properties":{"now":{"type":"integer"},"months":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string"},"headcount":{"type":"integer"}},"required":["month","headcount"],"additionalProperties":false}}},"required":["now","months"],"additionalProperties":false},"joining_this_month":{"type":"array","items":{"type":"object","properties":{"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"date":{"type":"string"}},"required":["person","date"],"additionalProperties":false}},"leaving_soon":{"type":"array","items":{"type":"object","properties":{"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"date":{"type":"string"}},"required":["person","date"],"additionalProperties":false}},"invites":{"type":"object","properties":{"pending":{"type":"integer"},"not_invited":{"type":"integer"}},"required":["pending","not_invited"],"additionalProperties":false},"needs":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["approvals","first_day","probation_ends","offboard","move_roles","contract_ends","invite_people","unit_heads","personal_details","no_manager"]},"date":{"type":"string","nullable":true},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"count":{"type":"integer","nullable":true},"ids":{"type":"array","items":{"type":"string"}},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true}},"required":["kind","date","person","manager","count","ids","contract_type"],"additionalProperties":false}},"coming":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["starts","last_day","probation_ends","contract_ends","job_change"]},"date":{"type":"string"},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"reason":{"type":"string","nullable":true},"title":{"type":"string","nullable":true}},"required":["kind","date","person","reason","title"],"additionalProperties":false}},"positions":{"type":"object","properties":{"open":{"type":"integer"},"on_hold":{"type":"integer"},"draft":{"type":"integer"},"past_target":{"type":"integer"}},"required":["open","on_hold","draft","past_target"],"additionalProperties":false},"checklists":{"type":"object","properties":{"open":{"type":"integer"},"overdue_tasks":{"type":"integer"},"runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"anchor_date":{"type":"string"},"progress":{"type":"object","properties":{"done":{"type":"integer"},"skipped":{"type":"integer"},"total":{"type":"integer"}},"required":["done","skipped","total"],"additionalProperties":false}},"required":["id","name","kind","person","anchor_date","progress"],"additionalProperties":false}}},"required":["open","overdue_tasks","runs"],"additionalProperties":false},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"link_url":{"type":"string","nullable":true},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true}},"required":["type","person"],"additionalProperties":false},"manager_missing":{"type":"boolean"},"offset_days":{"type":"integer"},"due_date":{"type":"string"},"visible_from":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","done","skipped"]},"resolved_at":{"type":"string","nullable":true},"resolved_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"skip_reason":{"type":"string","nullable":true},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"text":{"type":"string"},"at":{"type":"string"}},"required":["id","author","text","at"],"additionalProperties":false}},"can":{"type":"object","properties":{"tick":{"type":"boolean"},"skip":{"type":"boolean"},"reassign":{"type":"boolean"},"comment":{"type":"boolean"}},"required":["tick","skip","reassign","comment"],"additionalProperties":false},"run":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"status":{"type":"string","enum":["open","completed","cancelled"]},"anchor_date":{"type":"string","nullable":true}},"required":["id","name","kind","status","anchor_date"],"additionalProperties":false},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"required":["id","title","description","link_url","assignee","manager_missing","offset_days","due_date","visible_from","status","resolved_at","resolved_by","skip_reason","comments","can","run","person"],"additionalProperties":false}}},"required":["as_of","headcount","joining_this_month","leaving_soon","invites","needs","coming","positions","checklists","tasks"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/people.photo.upload":{"post":{"operationId":"org.people.photo.upload","summary":"Upload a person's photo","description":"Sets the profile photo of a person (owners, admins and HR). The image (image_base64: the file as base64) must be a JPEG, PNG or WebP of at most 2 MB and 24 megapixels (over MCP the request is limited to 2 MiB, so about 1.5 MB; send larger files through the REST API); the server checks the bytes, centre-crops it to a square, re-encodes it as a 512×512 WebP and drops all metadata (EXIF, location). A new upload replaces the old photo. The photo is visible to everyone in the organization who can see the person (public tier, also over the API and MCP as photo_url); never outside it. Returns the new photo_url (a path on the company address, fetched with the same credentials). Errors: not_found for unknown or erased people, validation_failed for an image that is not JPEG/PNG/WebP, too large or damaged, rate_limited when the server is busy with other images (retry in a few seconds). Use dry_run to check the image without saving it.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"person_id":{"type":"string","minLength":1},"image_base64":{"type":"string","minLength":1,"maxLength":2900000,"description":"The image file as base64 (a data: URL is accepted): JPEG, PNG or WebP, at most 2 MB. Square images work best; the server centre-crops."}},"required":["person_id","image_base64"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"person_id":{"type":"string"},"photo_url":{"type":"string","nullable":true}},"required":["person_id","photo_url"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/people.photo.remove":{"post":{"operationId":"org.people.photo.remove","summary":"Remove a person's photo","description":"Deletes the profile photo of a person (owners, admins and HR); their initials show instead. Succeeds when there is no photo. Errors: not_found for unknown or erased people.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"person_id":{"type":"string","minLength":1}},"required":["person_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"person_id":{"type":"string"},"photo_url":{"type":"string","nullable":true}},"required":["person_id","photo_url"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/me.photo.upload":{"post":{"operationId":"org.me.photo.upload","summary":"Upload my photo","description":"Sets your own profile photo. The image (image_base64: the file as base64) must be a JPEG, PNG or WebP of at most 2 MB and 24 megapixels (over MCP the request is limited to 2 MiB, so about 1.5 MB; send larger files through the REST API); the server checks the bytes, centre-crops it to a square, re-encodes it as a 512×512 WebP and drops all metadata (EXIF, location). A new upload replaces the old photo. The photo is visible to everyone in the organization who can see the person (public tier, also over the API and MCP as photo_url); never outside it. Returns the new photo_url. Errors: not_found when your login is not linked to a person, validation_failed for a bad image, rate_limited when the server is busy with other images (retry in a few seconds). Use dry_run first and confirm with the user.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image_base64":{"type":"string","minLength":1,"maxLength":2900000,"description":"The image file as base64 (a data: URL is accepted): JPEG, PNG or WebP, at most 2 MB. Square images work best; the server centre-crops."}},"required":["image_base64"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"person_id":{"type":"string"},"photo_url":{"type":"string","nullable":true}},"required":["person_id","photo_url"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/me.photo.remove":{"post":{"operationId":"org.me.photo.remove","summary":"Remove my photo","description":"Deletes your own profile photo; your initials show instead. Succeeds when there is no photo.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"person_id":{"type":"string"},"photo_url":{"type":"string","nullable":true}},"required":["person_id","photo_url"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/reminders.get":{"post":{"operationId":"org.reminders.get","summary":"Get reminder settings","description":"Returns the HR reminder email settings: probation ending (lead_days before the probation end date), fixed-term contract ending (lead_days before the contract end date), upcoming starters (lead_days before the first day, plus on_first_day) and work anniversaries (on the day). Each has enabled and its recipients: notify_hr (every owner, admin and HR member), notify_manager (the person's manager), and for anniversaries notify_person. Defaults: probation 14 days, contracts 30, starters 7 plus the first day, all on and to HR and the manager; anniversaries off. Emails go out once a day. Owners, admins and HR only.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"probation":{"type":"object","properties":{"enabled":{"type":"boolean"},"lead_days":{"type":"integer","minimum":0,"maximum":90},"notify_hr":{"type":"boolean"},"notify_manager":{"type":"boolean"}},"required":["enabled","lead_days","notify_hr","notify_manager"],"additionalProperties":false},"contract_end":{"type":"object","properties":{"enabled":{"type":"boolean"},"lead_days":{"type":"integer","minimum":0,"maximum":180},"notify_hr":{"type":"boolean"},"notify_manager":{"type":"boolean"}},"required":["enabled","lead_days","notify_hr","notify_manager"],"additionalProperties":false},"starters":{"type":"object","properties":{"enabled":{"type":"boolean"},"lead_days":{"type":"integer","minimum":1,"maximum":60},"on_first_day":{"type":"boolean"},"notify_hr":{"type":"boolean"},"notify_manager":{"type":"boolean"}},"required":["enabled","lead_days","on_first_day","notify_hr","notify_manager"],"additionalProperties":false},"anniversaries":{"type":"object","properties":{"enabled":{"type":"boolean"},"notify_hr":{"type":"boolean"},"notify_manager":{"type":"boolean"},"notify_person":{"type":"boolean"}},"required":["enabled","notify_hr","notify_manager","notify_person"],"additionalProperties":false},"updated_at":{"type":"string","nullable":true}},"required":["probation","contract_end","starters","anniversaries","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.reminders.get","summary":"Get reminder settings","description":"Returns the HR reminder email settings: probation ending (lead_days before the probation end date), fixed-term contract ending (lead_days before the contract end date), upcoming starters (lead_days before the first day, plus on_first_day) and work anniversaries (on the day). Each has enabled and its recipients: notify_hr (every owner, admin and HR member), notify_manager (the person's manager), and for anniversaries notify_person. Defaults: probation 14 days, contracts 30, starters 7 plus the first day, all on and to HR and the manager; anniversaries off. Emails go out once a day. Owners, admins and HR only.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"probation":{"type":"object","properties":{"enabled":{"type":"boolean"},"lead_days":{"type":"integer","minimum":0,"maximum":90},"notify_hr":{"type":"boolean"},"notify_manager":{"type":"boolean"}},"required":["enabled","lead_days","notify_hr","notify_manager"],"additionalProperties":false},"contract_end":{"type":"object","properties":{"enabled":{"type":"boolean"},"lead_days":{"type":"integer","minimum":0,"maximum":180},"notify_hr":{"type":"boolean"},"notify_manager":{"type":"boolean"}},"required":["enabled","lead_days","notify_hr","notify_manager"],"additionalProperties":false},"starters":{"type":"object","properties":{"enabled":{"type":"boolean"},"lead_days":{"type":"integer","minimum":1,"maximum":60},"on_first_day":{"type":"boolean"},"notify_hr":{"type":"boolean"},"notify_manager":{"type":"boolean"}},"required":["enabled","lead_days","on_first_day","notify_hr","notify_manager"],"additionalProperties":false},"anniversaries":{"type":"object","properties":{"enabled":{"type":"boolean"},"notify_hr":{"type":"boolean"},"notify_manager":{"type":"boolean"},"notify_person":{"type":"boolean"}},"required":["enabled","notify_hr","notify_manager","notify_person"],"additionalProperties":false},"updated_at":{"type":"string","nullable":true}},"required":["probation","contract_end","starters","anniversaries","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/reminders.update":{"post":{"operationId":"org.reminders.update","summary":"Change reminder settings","description":"Changes the HR reminder email settings (see org_reminders_get). Send only what changes, per reminder: probation, contract_end, starters and anniversaries, each with enabled, lead_days (probation 0–90, contract_end 0–180, starters 1–60; anniversaries have none), on_first_day (starters), notify_hr, notify_manager and notify_person (anniversaries). A reminder that is on must go to at least one recipient. Changes apply from the next daily run. The company must be set up first (org_setup_init). Use dry_run first. Owners, admins and HR only.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"probation":{"type":"object","properties":{"enabled":{"type":"boolean"},"lead_days":{"type":"integer","minimum":0,"maximum":90},"notify_hr":{"type":"boolean"},"notify_manager":{"type":"boolean"}},"additionalProperties":false},"contract_end":{"type":"object","properties":{"enabled":{"type":"boolean"},"lead_days":{"type":"integer","minimum":0,"maximum":180},"notify_hr":{"type":"boolean"},"notify_manager":{"type":"boolean"}},"additionalProperties":false},"starters":{"type":"object","properties":{"enabled":{"type":"boolean"},"lead_days":{"type":"integer","minimum":1,"maximum":60},"on_first_day":{"type":"boolean"},"notify_hr":{"type":"boolean"},"notify_manager":{"type":"boolean"}},"additionalProperties":false},"anniversaries":{"type":"object","properties":{"enabled":{"type":"boolean"},"notify_hr":{"type":"boolean"},"notify_manager":{"type":"boolean"},"notify_person":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"probation":{"type":"object","properties":{"enabled":{"type":"boolean"},"lead_days":{"type":"integer","minimum":0,"maximum":90},"notify_hr":{"type":"boolean"},"notify_manager":{"type":"boolean"}},"required":["enabled","lead_days","notify_hr","notify_manager"],"additionalProperties":false},"contract_end":{"type":"object","properties":{"enabled":{"type":"boolean"},"lead_days":{"type":"integer","minimum":0,"maximum":180},"notify_hr":{"type":"boolean"},"notify_manager":{"type":"boolean"}},"required":["enabled","lead_days","notify_hr","notify_manager"],"additionalProperties":false},"starters":{"type":"object","properties":{"enabled":{"type":"boolean"},"lead_days":{"type":"integer","minimum":1,"maximum":60},"on_first_day":{"type":"boolean"},"notify_hr":{"type":"boolean"},"notify_manager":{"type":"boolean"}},"required":["enabled","lead_days","on_first_day","notify_hr","notify_manager"],"additionalProperties":false},"anniversaries":{"type":"object","properties":{"enabled":{"type":"boolean"},"notify_hr":{"type":"boolean"},"notify_manager":{"type":"boolean"},"notify_person":{"type":"boolean"}},"required":["enabled","notify_hr","notify_manager","notify_person"],"additionalProperties":false},"updated_at":{"type":"string","nullable":true}},"required":["probation","contract_end","starters","anniversaries","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/reminders.upcoming":{"post":{"operationId":"org.reminders.upcoming","summary":"List upcoming reminders","description":"Lists what the enabled HR reminders cover in the next days (default 30, at most 90), soonest first: probation endings, fixed-term contract endings, people starting (start_soon, or start_today on their first day) and work anniversaries (with years). Each item has the date, remind_on (the day the email goes out, or today if it is already due), the person (name, title) and their manager. Owners, admins and HR only. Use it to answer \"what is coming up\" or to check the reminder settings do what the user expects.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer","minimum":1,"maximum":90,"default":30}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"today":{"type":"string"},"days":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["probation_end","contract_end","start_soon","start_today","anniversary"]},"date":{"type":"string"},"remind_on":{"type":"string"},"years":{"type":"integer","nullable":true},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true}},"required":["kind","date","remind_on","years","person","manager"],"additionalProperties":false}}},"required":["today","days","items"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.reminders.upcoming","summary":"List upcoming reminders","description":"Lists what the enabled HR reminders cover in the next days (default 30, at most 90), soonest first: probation endings, fixed-term contract endings, people starting (start_soon, or start_today on their first day) and work anniversaries (with years). Each item has the date, remind_on (the day the email goes out, or today if it is already due), the person (name, title) and their manager. Owners, admins and HR only. Use it to answer \"what is coming up\" or to check the reminder settings do what the user expects.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"today":{"type":"string"},"days":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["probation_end","contract_end","start_soon","start_today","anniversary"]},"date":{"type":"string"},"remind_on":{"type":"string"},"years":{"type":"integer","nullable":true},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true}},"required":["kind","date","remind_on","years","person","manager"],"additionalProperties":false}}},"required":["today","days","items"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/positions.list":{"post":{"operationId":"org.positions.list","summary":"List open positions (headcount plan)","description":"Lists open positions: roles the company plans to fill (title, team, location, legal entity, who it reports to — a person or another position —, contract type, weekly hours, target start date, status, reason \"new\" or \"replacement\" with the leaver it replaces, and who filled it). status: \"active\" (default: draft, open and on hold), one status (draft, open, on_hold, filled, cancelled), \"closed\" (filled and cancelled) or \"all\". Filled and cancelled positions come newest first, a page at a time: limit (default 50, at most 200) of them per call; for the next page pass after = the id of the last closed position you got (only with filled, cancelled, closed or all; with all the draft, open and on-hold ones come only on the first page). Filters: unit_id, reports_to_person_id. Who sees what: owners, admins and HR see every position; a manager sees only the open and on-hold positions that report to them or to someone below them (also when that person starts later or has left: the line they belong to); everyone else sees none (an empty list). notes are for owners, admins and HR only; pay_range (the budget) only for owners, admins and HR signed in to Bizisy, never over MCP or an API key (pay_range_hidden is then true); replaces is shown only when you may see that person's job details. can_reopen: a filled position whose hire did not start (org_positions_reopen).","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","draft","open","on_hold","filled","cancelled","closed","all"],"default":"active"},"unit_id":{"type":"string","minLength":1},"reports_to_person_id":{"type":"string","minLength":1},"limit":{"type":"integer","minimum":1,"maximum":200},"after":{"type":"string","minLength":1}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","open","on_hold","filled","cancelled"]},"reason":{"type":"string","enum":["new","replacement"]},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"reports_to_person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"reports_to_position":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false,"nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"weekly_hours":{"type":"number","nullable":true},"pay_range":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]}},"required":["min","max","currency","period"],"additionalProperties":false,"nullable":true},"pay_range_hidden":{"type":"boolean"},"target_start_date":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"replaces":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"filled_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"filled_on":{"type":"string","nullable":true},"can_reopen":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","status","reason","unit","location","legal_entity","reports_to_person","reports_to_position","contract_type","weekly_hours","pay_range","pay_range_hidden","target_start_date","notes","replaces","filled_by","filled_on","can_reopen","created_at","updated_at"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.positions.list","summary":"List open positions (headcount plan)","description":"Lists open positions: roles the company plans to fill (title, team, location, legal entity, who it reports to — a person or another position —, contract type, weekly hours, target start date, status, reason \"new\" or \"replacement\" with the leaver it replaces, and who filled it). status: \"active\" (default: draft, open and on hold), one status (draft, open, on_hold, filled, cancelled), \"closed\" (filled and cancelled) or \"all\". Filled and cancelled positions come newest first, a page at a time: limit (default 50, at most 200) of them per call; for the next page pass after = the id of the last closed position you got (only with filled, cancelled, closed or all; with all the draft, open and on-hold ones come only on the first page). Filters: unit_id, reports_to_person_id. Who sees what: owners, admins and HR see every position; a manager sees only the open and on-hold positions that report to them or to someone below them (also when that person starts later or has left: the line they belong to); everyone else sees none (an empty list). notes are for owners, admins and HR only; pay_range (the budget) only for owners, admins and HR signed in to Bizisy, never over MCP or an API key (pay_range_hidden is then true); replaces is shown only when you may see that person's job details. can_reopen: a filled position whose hire did not start (org_positions_reopen).","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","open","on_hold","filled","cancelled"]},"reason":{"type":"string","enum":["new","replacement"]},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"reports_to_person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"reports_to_position":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false,"nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"weekly_hours":{"type":"number","nullable":true},"pay_range":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]}},"required":["min","max","currency","period"],"additionalProperties":false,"nullable":true},"pay_range_hidden":{"type":"boolean"},"target_start_date":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"replaces":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"filled_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"filled_on":{"type":"string","nullable":true},"can_reopen":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","status","reason","unit","location","legal_entity","reports_to_person","reports_to_position","contract_type","weekly_hours","pay_range","pay_range_hidden","target_start_date","notes","replaces","filled_by","filled_on","can_reopen","created_at","updated_at"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/positions.get":{"post":{"operationId":"org.positions.get","summary":"Get an open position","description":"Returns one position with the same visibility as org_positions_list: owners, admins and HR any position (filled and cancelled ones too); a manager the open and on-hold positions in their line; otherwise not_found.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"position_id":{"type":"string","minLength":1}},"required":["position_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","open","on_hold","filled","cancelled"]},"reason":{"type":"string","enum":["new","replacement"]},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"reports_to_person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"reports_to_position":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false,"nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"weekly_hours":{"type":"number","nullable":true},"pay_range":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]}},"required":["min","max","currency","period"],"additionalProperties":false,"nullable":true},"pay_range_hidden":{"type":"boolean"},"target_start_date":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"replaces":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"filled_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"filled_on":{"type":"string","nullable":true},"can_reopen":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","status","reason","unit","location","legal_entity","reports_to_person","reports_to_position","contract_type","weekly_hours","pay_range","pay_range_hidden","target_start_date","notes","replaces","filled_by","filled_on","can_reopen","created_at","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.positions.get","summary":"Get an open position","description":"Returns one position with the same visibility as org_positions_list: owners, admins and HR any position (filled and cancelled ones too); a manager the open and on-hold positions in their line; otherwise not_found.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","open","on_hold","filled","cancelled"]},"reason":{"type":"string","enum":["new","replacement"]},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"reports_to_person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"reports_to_position":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false,"nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"weekly_hours":{"type":"number","nullable":true},"pay_range":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]}},"required":["min","max","currency","period"],"additionalProperties":false,"nullable":true},"pay_range_hidden":{"type":"boolean"},"target_start_date":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"replaces":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"filled_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"filled_on":{"type":"string","nullable":true},"can_reopen":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","status","reason","unit","location","legal_entity","reports_to_person","reports_to_position","contract_type","weekly_hours","pay_range","pay_range_hidden","target_start_date","notes","replaces","filled_by","filled_on","can_reopen","created_at","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/positions.create":{"post":{"operationId":"org.positions.create","summary":"Create an open position","description":"Plans a role to fill. Required: title. Optional: status (open by default, or draft or on_hold), unit_id, location_id and legal_entity_id (default to the only active one), reports_to_person_id (someone employed now or starting soon) or reports_to_position_id (another draft, open or on-hold position; never both), contract_type, weekly_hours, target_start_date (YYYY-MM-DD), notes (owners, admins and HR only; do not put personal data here), reason (\"new\", default, or \"replacement\" with an optional replaces_person_id: the leaver), and pay_range {min, max, currency, period: year, month or hour} — the budget, which can only be set by signing in to Bizisy (refused over MCP or an API key). At most 500 draft, open or on-hold positions per organization. Owners, admins and HR. Use dry_run first. To fill it, hire someone with org_people_hire and position_id.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"status":{"type":"string","enum":["draft","open","on_hold"]},"unit_id":{"type":"string","minLength":1,"nullable":true},"location_id":{"type":"string","minLength":1,"nullable":true},"legal_entity_id":{"type":"string","minLength":1,"nullable":true},"reports_to_person_id":{"type":"string","minLength":1,"nullable":true},"reports_to_position_id":{"type":"string","minLength":1,"nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"weekly_hours":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":80,"nullable":true},"pay_range":{"type":"object","properties":{"min":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":100000000},"max":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":100000000},"currency":{"allOf":[{"type":"string"},{"type":"string","pattern":"^[A-Z]{3}$"}]},"period":{"type":"string","enum":["year","month","hour"]}},"required":["min","max","currency","period"],"additionalProperties":false,"nullable":true},"target_start_date":{"type":"string","nullable":true},"notes":{"type":"string","maxLength":1000,"nullable":true},"reason":{"type":"string","enum":["new","replacement"]},"replaces_person_id":{"type":"string","minLength":1,"nullable":true}},"required":["title"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","open","on_hold","filled","cancelled"]},"reason":{"type":"string","enum":["new","replacement"]},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"reports_to_person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"reports_to_position":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false,"nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"weekly_hours":{"type":"number","nullable":true},"pay_range":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]}},"required":["min","max","currency","period"],"additionalProperties":false,"nullable":true},"pay_range_hidden":{"type":"boolean"},"target_start_date":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"replaces":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"filled_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"filled_on":{"type":"string","nullable":true},"can_reopen":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","status","reason","unit","location","legal_entity","reports_to_person","reports_to_position","contract_type","weekly_hours","pay_range","pay_range_hidden","target_start_date","notes","replaces","filled_by","filled_on","can_reopen","created_at","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/positions.update":{"post":{"operationId":"org.positions.update","summary":"Change an open position","description":"Changes a position: any field of org_positions_create (null clears one; setting reports_to_person_id clears reports_to_position_id and the other way round; reason \"new\" clears replaces_person_id) and status: draft → open, on_hold or cancelled; open ↔ on_hold; open or on hold → cancelled; cancelled → draft or open (reopen; who it reports to is checked again). Cancelling a position moves the positions that reported to it to whoever it reported to. \"filled\" is never set here: hire into the position with org_people_hire and position_id. A filled position only takes notes; if its hire did not start, reopen it with org_positions_reopen. pay_range can only be changed by signing in to Bizisy (refused over MCP or an API key; leave it out to keep it). Owners, admins and HR.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"position_id":{"type":"string","minLength":1},"title":{"type":"string","minLength":1,"maxLength":120},"status":{"type":"string","enum":["draft","open","on_hold","filled","cancelled"]},"unit_id":{"type":"string","minLength":1,"nullable":true},"location_id":{"type":"string","minLength":1,"nullable":true},"legal_entity_id":{"type":"string","minLength":1,"nullable":true},"reports_to_person_id":{"type":"string","minLength":1,"nullable":true},"reports_to_position_id":{"type":"string","minLength":1,"nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"weekly_hours":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":80,"nullable":true},"pay_range":{"type":"object","properties":{"min":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":100000000},"max":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":100000000},"currency":{"allOf":[{"type":"string"},{"type":"string","pattern":"^[A-Z]{3}$"}]},"period":{"type":"string","enum":["year","month","hour"]}},"required":["min","max","currency","period"],"additionalProperties":false,"nullable":true},"target_start_date":{"type":"string","nullable":true},"notes":{"type":"string","maxLength":1000,"nullable":true},"reason":{"type":"string","enum":["new","replacement"]},"replaces_person_id":{"type":"string","minLength":1,"nullable":true}},"required":["position_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","open","on_hold","filled","cancelled"]},"reason":{"type":"string","enum":["new","replacement"]},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"reports_to_person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"reports_to_position":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false,"nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"weekly_hours":{"type":"number","nullable":true},"pay_range":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]}},"required":["min","max","currency","period"],"additionalProperties":false,"nullable":true},"pay_range_hidden":{"type":"boolean"},"target_start_date":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"replaces":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"filled_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"filled_on":{"type":"string","nullable":true},"can_reopen":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","status","reason","unit","location","legal_entity","reports_to_person","reports_to_position","contract_type","weekly_hours","pay_range","pay_range_hidden","target_start_date","notes","replaces","filled_by","filled_on","can_reopen","created_at","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/positions.reopen":{"post":{"operationId":"org.positions.reopen","summary":"Reopen a filled position (the hire did not start)","description":"Puts a filled position back to open when its hire fell through: the person was terminated on or before their start date, or erased (can_reopen in org_positions_get). The positions that were moved under that person go back under this position, and their job no longer records it. Refused otherwise (conflict). Owners, admins and HR.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"position_id":{"type":"string","minLength":1}},"required":["position_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","open","on_hold","filled","cancelled"]},"reason":{"type":"string","enum":["new","replacement"]},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"reports_to_person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"reports_to_position":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false,"nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"weekly_hours":{"type":"number","nullable":true},"pay_range":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]}},"required":["min","max","currency","period"],"additionalProperties":false,"nullable":true},"pay_range_hidden":{"type":"boolean"},"target_start_date":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"replaces":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"filled_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"filled_on":{"type":"string","nullable":true},"can_reopen":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","status","reason","unit","location","legal_entity","reports_to_person","reports_to_position","contract_type","weekly_hours","pay_range","pay_range_hidden","target_start_date","notes","replaces","filled_by","filled_on","can_reopen","created_at","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/approvals.settings.get":{"post":{"operationId":"org.approvals.settings.get","summary":"Get approval settings","description":"Returns who must approve each kind of change before it takes effect: job_change (title, team, manager, location, legal entity, employment type, FTE, contract terms; org_people_change_job), termination (org_people_terminate) and pay_change (org_pay_add). Modes: off (no approval: the change applies at once; the default), hr (an owner, admin or HR member), manager (the person's manager today; when they have no manager, the team lead of their team or of a team above it decides; HR when no one of them can sign in, or when the manager proposed the change), manager_then_hr (both, in that order). Pay offers off and hr only. hr_approvers is how many owners, admins and HR members can approve. Owners, admins and HR.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"job_change":{"type":"string","enum":["off","hr","manager","manager_then_hr"]},"termination":{"type":"string","enum":["off","hr","manager","manager_then_hr"]},"pay_change":{"type":"string","enum":["off","hr","manager","manager_then_hr"]},"updated_at":{"type":"string","nullable":true},"hr_approvers":{"type":"integer"}},"required":["job_change","termination","pay_change","updated_at","hr_approvers"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.approvals.settings.get","summary":"Get approval settings","description":"Returns who must approve each kind of change before it takes effect: job_change (title, team, manager, location, legal entity, employment type, FTE, contract terms; org_people_change_job), termination (org_people_terminate) and pay_change (org_pay_add). Modes: off (no approval: the change applies at once; the default), hr (an owner, admin or HR member), manager (the person's manager today; when they have no manager, the team lead of their team or of a team above it decides; HR when no one of them can sign in, or when the manager proposed the change), manager_then_hr (both, in that order). Pay offers off and hr only. hr_approvers is how many owners, admins and HR members can approve. Owners, admins and HR.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"job_change":{"type":"string","enum":["off","hr","manager","manager_then_hr"]},"termination":{"type":"string","enum":["off","hr","manager","manager_then_hr"]},"pay_change":{"type":"string","enum":["off","hr","manager","manager_then_hr"]},"updated_at":{"type":"string","nullable":true},"hr_approvers":{"type":"integer"}},"required":["job_change","termination","pay_change","updated_at","hr_approvers"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/approvals.settings.update":{"post":{"operationId":"org.approvals.settings.update","summary":"Change approval settings","description":"Sets who approves each kind of change (see org_approvals_settings_get): job_change, termination and pay_change, each off, hr, manager or manager_then_hr (pay: off or hr). Send only what changes. Requests already waiting keep the steps they were created with. Owners and admins only, and only in the app: never over an API key or MCP, so an assistant can never switch approval off.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_change":{"type":"string","enum":["off","hr","manager","manager_then_hr"]},"termination":{"type":"string","enum":["off","hr","manager","manager_then_hr"]},"pay_change":{"type":"string","enum":["off","hr"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"job_change":{"type":"string","enum":["off","hr","manager","manager_then_hr"]},"termination":{"type":"string","enum":["off","hr","manager","manager_then_hr"]},"pay_change":{"type":"string","enum":["off","hr","manager","manager_then_hr"]},"updated_at":{"type":"string","nullable":true},"hr_approvers":{"type":"integer"}},"required":["job_change","termination","pay_change","updated_at","hr_approvers"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/approvals.list":{"post":{"operationId":"org.approvals.list","summary":"List approval requests","description":"Lists change requests you may see: status open (default: waiting for a decision), closed (approved, rejected, withdrawn, outdated or expired; newest first, at most 100) or all; person_id narrows to one person; waiting_for_me only those you can decide now. waiting_for_me in the result counts requests you can decide (over an API key: that its user can decide in the app). Each request has the change (job_change before/after, termination last day and reason, or pay_change amount), the effective date, the steps with who approved or can approve, and can_decide. You see job and termination requests as HR, as one of the person's managers, as the proposer, or as the team lead deciding it (while it waits for you, and after you decided); pay requests only as HR in the app; never requests about yourself. Approving needs the app (org_approvals_approve refuses API keys).","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["open","closed","all"],"default":"open"},"person_id":{"type":"string","minLength":1},"waiting_for_me":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["job_change","termination","pay_change"]},"status":{"type":"string","enum":["pending","approved","rejected","cancelled","outdated","expired"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"effective_date":{"type":"string"},"expires_on":{"type":"string"},"change":{"type":"string","enum":["change_job","terminate","pay_add","correct_job","rehire","pay_remove"]},"job_change":{"type":"object","properties":{"reason":{"type":"string","enum":["change","promotion","transfer","correction","rehire"]},"before":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"after":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false}},"required":["reason","before","after"],"additionalProperties":false,"nullable":true},"termination":{"type":"object","properties":{"last_day":{"type":"string"},"reason":{"type":"string","nullable":true},"job":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"change":{"type":"string","enum":["end","move","cancel"]}},"required":["last_day","reason","job","change"],"additionalProperties":false,"nullable":true},"pay_change":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","nullable":true},"before":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string"},"valid_from":{"type":"string"}},"required":["amount","currency","period","valid_from"],"additionalProperties":false,"nullable":true},"removes":{"type":"boolean"}},"required":["amount","currency","period","note","before","removes"],"additionalProperties":false,"nullable":true},"proposed_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true},"via":{"type":"string","enum":["app","api"]}},"required":["name","person_id","via"],"additionalProperties":false},"proposed_at":{"type":"string"},"steps":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["manager","hr"]},"state":{"type":"string","enum":["waiting","pending","approved","rejected"]},"fallback":{"type":"boolean"},"team_lead":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"reason":{"type":"string","enum":["no_manager","manager_left"]}},"required":["unit_id","unit_name","reason"],"additionalProperties":false,"nullable":true},"team_lead_blocked":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"what":{"type":"string","enum":["lead","removed","moved","archived"]}},"required":["unit_id","unit_name","what"],"additionalProperties":false,"nullable":true},"untrusted":{"type":"string","enum":["no_login","invited_by_proposer"],"nullable":true},"decided_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true}},"required":["name","person_id"],"additionalProperties":false,"nullable":true},"decided_at":{"type":"string","nullable":true},"comment":{"type":"string","nullable":true},"auto":{"type":"string","enum":["proposed_by_approver","no_other_approver"],"nullable":true},"approvers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true},"is_viewer":{"type":"boolean"}},"required":["name","person_id","is_viewer"],"additionalProperties":false}}},"required":["role","state","fallback","team_lead","team_lead_blocked","untrusted","decided_by","decided_at","comment","auto","approvers"],"additionalProperties":false}},"closed_at":{"type":"string","nullable":true},"closed_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true}},"required":["name","person_id"],"additionalProperties":false,"nullable":true},"can_decide":{"type":"boolean"},"can_cancel":{"type":"boolean"},"is_proposer":{"type":"boolean"},"can_reject":{"type":"boolean"}},"required":["id","kind","status","person","effective_date","expires_on","change","job_change","termination","pay_change","proposed_by","proposed_at","steps","closed_at","closed_by","can_decide","can_cancel","is_proposer","can_reject"],"additionalProperties":false}},"waiting_for_me":{"type":"integer"}},"required":["items","waiting_for_me"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.approvals.list","summary":"List approval requests","description":"Lists change requests you may see: status open (default: waiting for a decision), closed (approved, rejected, withdrawn, outdated or expired; newest first, at most 100) or all; person_id narrows to one person; waiting_for_me only those you can decide now. waiting_for_me in the result counts requests you can decide (over an API key: that its user can decide in the app). Each request has the change (job_change before/after, termination last day and reason, or pay_change amount), the effective date, the steps with who approved or can approve, and can_decide. You see job and termination requests as HR, as one of the person's managers, as the proposer, or as the team lead deciding it (while it waits for you, and after you decided); pay requests only as HR in the app; never requests about yourself. Approving needs the app (org_approvals_approve refuses API keys).","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["job_change","termination","pay_change"]},"status":{"type":"string","enum":["pending","approved","rejected","cancelled","outdated","expired"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"effective_date":{"type":"string"},"expires_on":{"type":"string"},"change":{"type":"string","enum":["change_job","terminate","pay_add","correct_job","rehire","pay_remove"]},"job_change":{"type":"object","properties":{"reason":{"type":"string","enum":["change","promotion","transfer","correction","rehire"]},"before":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"after":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false}},"required":["reason","before","after"],"additionalProperties":false,"nullable":true},"termination":{"type":"object","properties":{"last_day":{"type":"string"},"reason":{"type":"string","nullable":true},"job":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"change":{"type":"string","enum":["end","move","cancel"]}},"required":["last_day","reason","job","change"],"additionalProperties":false,"nullable":true},"pay_change":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","nullable":true},"before":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string"},"valid_from":{"type":"string"}},"required":["amount","currency","period","valid_from"],"additionalProperties":false,"nullable":true},"removes":{"type":"boolean"}},"required":["amount","currency","period","note","before","removes"],"additionalProperties":false,"nullable":true},"proposed_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true},"via":{"type":"string","enum":["app","api"]}},"required":["name","person_id","via"],"additionalProperties":false},"proposed_at":{"type":"string"},"steps":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["manager","hr"]},"state":{"type":"string","enum":["waiting","pending","approved","rejected"]},"fallback":{"type":"boolean"},"team_lead":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"reason":{"type":"string","enum":["no_manager","manager_left"]}},"required":["unit_id","unit_name","reason"],"additionalProperties":false,"nullable":true},"team_lead_blocked":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"what":{"type":"string","enum":["lead","removed","moved","archived"]}},"required":["unit_id","unit_name","what"],"additionalProperties":false,"nullable":true},"untrusted":{"type":"string","enum":["no_login","invited_by_proposer"],"nullable":true},"decided_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true}},"required":["name","person_id"],"additionalProperties":false,"nullable":true},"decided_at":{"type":"string","nullable":true},"comment":{"type":"string","nullable":true},"auto":{"type":"string","enum":["proposed_by_approver","no_other_approver"],"nullable":true},"approvers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true},"is_viewer":{"type":"boolean"}},"required":["name","person_id","is_viewer"],"additionalProperties":false}}},"required":["role","state","fallback","team_lead","team_lead_blocked","untrusted","decided_by","decided_at","comment","auto","approvers"],"additionalProperties":false}},"closed_at":{"type":"string","nullable":true},"closed_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true}},"required":["name","person_id"],"additionalProperties":false,"nullable":true},"can_decide":{"type":"boolean"},"can_cancel":{"type":"boolean"},"is_proposer":{"type":"boolean"},"can_reject":{"type":"boolean"}},"required":["id","kind","status","person","effective_date","expires_on","change","job_change","termination","pay_change","proposed_by","proposed_at","steps","closed_at","closed_by","can_decide","can_cancel","is_proposer","can_reject"],"additionalProperties":false}},"waiting_for_me":{"type":"integer"}},"required":["items","waiting_for_me"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/approvals.get":{"post":{"operationId":"org.approvals.get","summary":"Get an approval request","description":"Returns one change request (see org_approvals_list) with its change, steps, comments and whether you can decide or withdraw it.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"approval_id":{"type":"string","minLength":1}},"required":["approval_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["job_change","termination","pay_change"]},"status":{"type":"string","enum":["pending","approved","rejected","cancelled","outdated","expired"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"effective_date":{"type":"string"},"expires_on":{"type":"string"},"change":{"type":"string","enum":["change_job","terminate","pay_add","correct_job","rehire","pay_remove"]},"job_change":{"type":"object","properties":{"reason":{"type":"string","enum":["change","promotion","transfer","correction","rehire"]},"before":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"after":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false}},"required":["reason","before","after"],"additionalProperties":false,"nullable":true},"termination":{"type":"object","properties":{"last_day":{"type":"string"},"reason":{"type":"string","nullable":true},"job":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"change":{"type":"string","enum":["end","move","cancel"]}},"required":["last_day","reason","job","change"],"additionalProperties":false,"nullable":true},"pay_change":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","nullable":true},"before":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string"},"valid_from":{"type":"string"}},"required":["amount","currency","period","valid_from"],"additionalProperties":false,"nullable":true},"removes":{"type":"boolean"}},"required":["amount","currency","period","note","before","removes"],"additionalProperties":false,"nullable":true},"proposed_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true},"via":{"type":"string","enum":["app","api"]}},"required":["name","person_id","via"],"additionalProperties":false},"proposed_at":{"type":"string"},"steps":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["manager","hr"]},"state":{"type":"string","enum":["waiting","pending","approved","rejected"]},"fallback":{"type":"boolean"},"team_lead":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"reason":{"type":"string","enum":["no_manager","manager_left"]}},"required":["unit_id","unit_name","reason"],"additionalProperties":false,"nullable":true},"team_lead_blocked":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"what":{"type":"string","enum":["lead","removed","moved","archived"]}},"required":["unit_id","unit_name","what"],"additionalProperties":false,"nullable":true},"untrusted":{"type":"string","enum":["no_login","invited_by_proposer"],"nullable":true},"decided_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true}},"required":["name","person_id"],"additionalProperties":false,"nullable":true},"decided_at":{"type":"string","nullable":true},"comment":{"type":"string","nullable":true},"auto":{"type":"string","enum":["proposed_by_approver","no_other_approver"],"nullable":true},"approvers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true},"is_viewer":{"type":"boolean"}},"required":["name","person_id","is_viewer"],"additionalProperties":false}}},"required":["role","state","fallback","team_lead","team_lead_blocked","untrusted","decided_by","decided_at","comment","auto","approvers"],"additionalProperties":false}},"closed_at":{"type":"string","nullable":true},"closed_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true}},"required":["name","person_id"],"additionalProperties":false,"nullable":true},"can_decide":{"type":"boolean"},"can_cancel":{"type":"boolean"},"is_proposer":{"type":"boolean"},"can_reject":{"type":"boolean"}},"required":["id","kind","status","person","effective_date","expires_on","change","job_change","termination","pay_change","proposed_by","proposed_at","steps","closed_at","closed_by","can_decide","can_cancel","is_proposer","can_reject"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.approvals.get","summary":"Get an approval request","description":"Returns one change request (see org_approvals_list) with its change, steps, comments and whether you can decide or withdraw it.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["job_change","termination","pay_change"]},"status":{"type":"string","enum":["pending","approved","rejected","cancelled","outdated","expired"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"effective_date":{"type":"string"},"expires_on":{"type":"string"},"change":{"type":"string","enum":["change_job","terminate","pay_add","correct_job","rehire","pay_remove"]},"job_change":{"type":"object","properties":{"reason":{"type":"string","enum":["change","promotion","transfer","correction","rehire"]},"before":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"after":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false}},"required":["reason","before","after"],"additionalProperties":false,"nullable":true},"termination":{"type":"object","properties":{"last_day":{"type":"string"},"reason":{"type":"string","nullable":true},"job":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"change":{"type":"string","enum":["end","move","cancel"]}},"required":["last_day","reason","job","change"],"additionalProperties":false,"nullable":true},"pay_change":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","nullable":true},"before":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string"},"valid_from":{"type":"string"}},"required":["amount","currency","period","valid_from"],"additionalProperties":false,"nullable":true},"removes":{"type":"boolean"}},"required":["amount","currency","period","note","before","removes"],"additionalProperties":false,"nullable":true},"proposed_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true},"via":{"type":"string","enum":["app","api"]}},"required":["name","person_id","via"],"additionalProperties":false},"proposed_at":{"type":"string"},"steps":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["manager","hr"]},"state":{"type":"string","enum":["waiting","pending","approved","rejected"]},"fallback":{"type":"boolean"},"team_lead":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"reason":{"type":"string","enum":["no_manager","manager_left"]}},"required":["unit_id","unit_name","reason"],"additionalProperties":false,"nullable":true},"team_lead_blocked":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"what":{"type":"string","enum":["lead","removed","moved","archived"]}},"required":["unit_id","unit_name","what"],"additionalProperties":false,"nullable":true},"untrusted":{"type":"string","enum":["no_login","invited_by_proposer"],"nullable":true},"decided_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true}},"required":["name","person_id"],"additionalProperties":false,"nullable":true},"decided_at":{"type":"string","nullable":true},"comment":{"type":"string","nullable":true},"auto":{"type":"string","enum":["proposed_by_approver","no_other_approver"],"nullable":true},"approvers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true},"is_viewer":{"type":"boolean"}},"required":["name","person_id","is_viewer"],"additionalProperties":false}}},"required":["role","state","fallback","team_lead","team_lead_blocked","untrusted","decided_by","decided_at","comment","auto","approvers"],"additionalProperties":false}},"closed_at":{"type":"string","nullable":true},"closed_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true}},"required":["name","person_id"],"additionalProperties":false,"nullable":true},"can_decide":{"type":"boolean"},"can_cancel":{"type":"boolean"},"is_proposer":{"type":"boolean"},"can_reject":{"type":"boolean"}},"required":["id","kind","status","person","effective_date","expires_on","change","job_change","termination","pay_change","proposed_by","proposed_at","steps","closed_at","closed_by","can_decide","can_cancel","is_proposer","can_reject"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/approvals.approve":{"post":{"operationId":"org.approvals.approve","summary":"Approve a change request","description":"Approves the step of a request that is waiting for you, with an optional comment. On the last step the change is applied exactly as org_people_change_job, org_people_terminate or org_pay_add would apply it (same checks, effective date and warnings); if it can no longer apply (for example the new manager left) approving is refused with the reason, and you can reject it instead. A request whose effective date passed is recorded backdated; 30 days after it, it expires. Only in the app, by the step's approver: the person's manager (with no manager: the team lead the request names in team_lead), or an owner, admin or HR member; never the proposer of an app request, never about yourself. Over an API key or MCP it is refused.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"approval_id":{"type":"string","minLength":1},"comment":{"type":"string","maxLength":500},"step":{"type":"integer","minimum":0,"maximum":5}},"required":["approval_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["job_change","termination","pay_change"]},"status":{"type":"string","enum":["pending","approved","rejected","cancelled","outdated","expired"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"effective_date":{"type":"string"},"expires_on":{"type":"string"},"change":{"type":"string","enum":["change_job","terminate","pay_add","correct_job","rehire","pay_remove"]},"job_change":{"type":"object","properties":{"reason":{"type":"string","enum":["change","promotion","transfer","correction","rehire"]},"before":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"after":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false}},"required":["reason","before","after"],"additionalProperties":false,"nullable":true},"termination":{"type":"object","properties":{"last_day":{"type":"string"},"reason":{"type":"string","nullable":true},"job":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"change":{"type":"string","enum":["end","move","cancel"]}},"required":["last_day","reason","job","change"],"additionalProperties":false,"nullable":true},"pay_change":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","nullable":true},"before":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string"},"valid_from":{"type":"string"}},"required":["amount","currency","period","valid_from"],"additionalProperties":false,"nullable":true},"removes":{"type":"boolean"}},"required":["amount","currency","period","note","before","removes"],"additionalProperties":false,"nullable":true},"proposed_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true},"via":{"type":"string","enum":["app","api"]}},"required":["name","person_id","via"],"additionalProperties":false},"proposed_at":{"type":"string"},"steps":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["manager","hr"]},"state":{"type":"string","enum":["waiting","pending","approved","rejected"]},"fallback":{"type":"boolean"},"team_lead":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"reason":{"type":"string","enum":["no_manager","manager_left"]}},"required":["unit_id","unit_name","reason"],"additionalProperties":false,"nullable":true},"team_lead_blocked":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"what":{"type":"string","enum":["lead","removed","moved","archived"]}},"required":["unit_id","unit_name","what"],"additionalProperties":false,"nullable":true},"untrusted":{"type":"string","enum":["no_login","invited_by_proposer"],"nullable":true},"decided_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true}},"required":["name","person_id"],"additionalProperties":false,"nullable":true},"decided_at":{"type":"string","nullable":true},"comment":{"type":"string","nullable":true},"auto":{"type":"string","enum":["proposed_by_approver","no_other_approver"],"nullable":true},"approvers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true},"is_viewer":{"type":"boolean"}},"required":["name","person_id","is_viewer"],"additionalProperties":false}}},"required":["role","state","fallback","team_lead","team_lead_blocked","untrusted","decided_by","decided_at","comment","auto","approvers"],"additionalProperties":false}},"closed_at":{"type":"string","nullable":true},"closed_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true}},"required":["name","person_id"],"additionalProperties":false,"nullable":true},"can_decide":{"type":"boolean"},"can_cancel":{"type":"boolean"},"is_proposer":{"type":"boolean"},"can_reject":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["id","kind","status","person","effective_date","expires_on","change","job_change","termination","pay_change","proposed_by","proposed_at","steps","closed_at","closed_by","can_decide","can_cancel","is_proposer","can_reject","warnings"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/approvals.reject":{"post":{"operationId":"org.approvals.reject","summary":"Reject a change request","description":"Rejects a request; comment (required) says why, for the proposer. Nothing changes on the person. In the app only, by the step's approver, or by any owner, admin or HR member (so a request waiting for a manager never holds the person up), never about yourself.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"approval_id":{"type":"string","minLength":1},"comment":{"allOf":[{"type":"string","maxLength":500},{"type":"string","minLength":1}]},"step":{"type":"integer","minimum":0,"maximum":5}},"required":["approval_id","comment"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["job_change","termination","pay_change"]},"status":{"type":"string","enum":["pending","approved","rejected","cancelled","outdated","expired"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"effective_date":{"type":"string"},"expires_on":{"type":"string"},"change":{"type":"string","enum":["change_job","terminate","pay_add","correct_job","rehire","pay_remove"]},"job_change":{"type":"object","properties":{"reason":{"type":"string","enum":["change","promotion","transfer","correction","rehire"]},"before":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"after":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false}},"required":["reason","before","after"],"additionalProperties":false,"nullable":true},"termination":{"type":"object","properties":{"last_day":{"type":"string"},"reason":{"type":"string","nullable":true},"job":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"change":{"type":"string","enum":["end","move","cancel"]}},"required":["last_day","reason","job","change"],"additionalProperties":false,"nullable":true},"pay_change":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","nullable":true},"before":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string"},"valid_from":{"type":"string"}},"required":["amount","currency","period","valid_from"],"additionalProperties":false,"nullable":true},"removes":{"type":"boolean"}},"required":["amount","currency","period","note","before","removes"],"additionalProperties":false,"nullable":true},"proposed_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true},"via":{"type":"string","enum":["app","api"]}},"required":["name","person_id","via"],"additionalProperties":false},"proposed_at":{"type":"string"},"steps":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["manager","hr"]},"state":{"type":"string","enum":["waiting","pending","approved","rejected"]},"fallback":{"type":"boolean"},"team_lead":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"reason":{"type":"string","enum":["no_manager","manager_left"]}},"required":["unit_id","unit_name","reason"],"additionalProperties":false,"nullable":true},"team_lead_blocked":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"what":{"type":"string","enum":["lead","removed","moved","archived"]}},"required":["unit_id","unit_name","what"],"additionalProperties":false,"nullable":true},"untrusted":{"type":"string","enum":["no_login","invited_by_proposer"],"nullable":true},"decided_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true}},"required":["name","person_id"],"additionalProperties":false,"nullable":true},"decided_at":{"type":"string","nullable":true},"comment":{"type":"string","nullable":true},"auto":{"type":"string","enum":["proposed_by_approver","no_other_approver"],"nullable":true},"approvers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true},"is_viewer":{"type":"boolean"}},"required":["name","person_id","is_viewer"],"additionalProperties":false}}},"required":["role","state","fallback","team_lead","team_lead_blocked","untrusted","decided_by","decided_at","comment","auto","approvers"],"additionalProperties":false}},"closed_at":{"type":"string","nullable":true},"closed_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true}},"required":["name","person_id"],"additionalProperties":false,"nullable":true},"can_decide":{"type":"boolean"},"can_cancel":{"type":"boolean"},"is_proposer":{"type":"boolean"},"can_reject":{"type":"boolean"}},"required":["id","kind","status","person","effective_date","expires_on","change","job_change","termination","pay_change","proposed_by","proposed_at","steps","closed_at","closed_by","can_decide","can_cancel","is_proposer","can_reject"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/approvals.cancel":{"post":{"operationId":"org.approvals.cancel","summary":"Withdraw a change request","description":"Withdraws a request that is waiting (or expired): nothing changes on the person. The proposer, or an owner, admin or HR member who can see it. Works over an API key for job and termination requests.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"approval_id":{"type":"string","minLength":1}},"required":["approval_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["job_change","termination","pay_change"]},"status":{"type":"string","enum":["pending","approved","rejected","cancelled","outdated","expired"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"effective_date":{"type":"string"},"expires_on":{"type":"string"},"change":{"type":"string","enum":["change_job","terminate","pay_add","correct_job","rehire","pay_remove"]},"job_change":{"type":"object","properties":{"reason":{"type":"string","enum":["change","promotion","transfer","correction","rehire"]},"before":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"after":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false}},"required":["reason","before","after"],"additionalProperties":false,"nullable":true},"termination":{"type":"object","properties":{"last_day":{"type":"string"},"reason":{"type":"string","nullable":true},"job":{"type":"object","properties":{"id":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"title":{"type":"string"},"unit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"legal_entity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true},"employment_type":{"type":"string","enum":["full_time","part_time","contractor","intern"]},"fte":{"type":"number"},"reason":{"type":"string"},"end_reason":{"type":"string","nullable":true},"contract_type":{"type":"string","enum":["permanent","fixed_term","temporary","internship","freelance"],"nullable":true},"contract_end_date":{"type":"string","nullable":true},"probation_end_date":{"type":"string","nullable":true},"weekly_hours":{"type":"number","nullable":true},"notice_period_days":{"type":"integer","nullable":true}},"required":["id","valid_from","valid_to","title","unit","manager","location","legal_entity","employment_type","fte","reason","end_reason","contract_type","contract_end_date","probation_end_date","weekly_hours","notice_period_days"],"additionalProperties":false,"nullable":true},"change":{"type":"string","enum":["end","move","cancel"]}},"required":["last_day","reason","job","change"],"additionalProperties":false,"nullable":true},"pay_change":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["year","month","hour"]},"note":{"type":"string","nullable":true},"before":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string"},"valid_from":{"type":"string"}},"required":["amount","currency","period","valid_from"],"additionalProperties":false,"nullable":true},"removes":{"type":"boolean"}},"required":["amount","currency","period","note","before","removes"],"additionalProperties":false,"nullable":true},"proposed_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true},"via":{"type":"string","enum":["app","api"]}},"required":["name","person_id","via"],"additionalProperties":false},"proposed_at":{"type":"string"},"steps":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["manager","hr"]},"state":{"type":"string","enum":["waiting","pending","approved","rejected"]},"fallback":{"type":"boolean"},"team_lead":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"reason":{"type":"string","enum":["no_manager","manager_left"]}},"required":["unit_id","unit_name","reason"],"additionalProperties":false,"nullable":true},"team_lead_blocked":{"type":"object","properties":{"unit_id":{"type":"string"},"unit_name":{"type":"string"},"what":{"type":"string","enum":["lead","removed","moved","archived"]}},"required":["unit_id","unit_name","what"],"additionalProperties":false,"nullable":true},"untrusted":{"type":"string","enum":["no_login","invited_by_proposer"],"nullable":true},"decided_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true}},"required":["name","person_id"],"additionalProperties":false,"nullable":true},"decided_at":{"type":"string","nullable":true},"comment":{"type":"string","nullable":true},"auto":{"type":"string","enum":["proposed_by_approver","no_other_approver"],"nullable":true},"approvers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true},"is_viewer":{"type":"boolean"}},"required":["name","person_id","is_viewer"],"additionalProperties":false}}},"required":["role","state","fallback","team_lead","team_lead_blocked","untrusted","decided_by","decided_at","comment","auto","approvers"],"additionalProperties":false}},"closed_at":{"type":"string","nullable":true},"closed_by":{"type":"object","properties":{"name":{"type":"string"},"person_id":{"type":"string","nullable":true}},"required":["name","person_id"],"additionalProperties":false,"nullable":true},"can_decide":{"type":"boolean"},"can_cancel":{"type":"boolean"},"is_proposer":{"type":"boolean"},"can_reject":{"type":"boolean"}},"required":["id","kind","status","person","effective_date","expires_on","change","job_change","termination","pay_change","proposed_by","proposed_at","steps","closed_at","closed_by","can_decide","can_cancel","is_proposer","can_reject"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/checklists.templates.list":{"post":{"operationId":"org.checklists.templates.list","summary":"List checklist templates","description":"Lists the company's checklist templates (Settings → Checklists): onboarding (due dates relative to the start date), offboarding (relative to the last day) and custom (relative to a date chosen when starting). Each has auto_start (onboarding and offboarding start by themselves when someone is hired or terminated), conditions (unit_ids — a unit includes its subunits —, location_ids, legal_entity_ids; empty = everyone; lists combine with AND) and tasks (title, description, link_url, assignee: hr | manager | person | member with a person, offset_days: negative = before). Until the company changes anything, the two starter templates Bizisy ships are listed with saved=false. Archived templates only with include_archived. Owners, admins and HR.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"include_archived":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"templates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"auto_start":{"type":"boolean"},"conditions":{"type":"object","properties":{"unit_ids":{"type":"array","items":{"type":"string"}},"location_ids":{"type":"array","items":{"type":"string"}},"legal_entity_ids":{"type":"array","items":{"type":"string"}}},"required":["unit_ids","location_ids","legal_entity_ids"],"additionalProperties":false},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"link_url":{"type":"string","nullable":true},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true}},"required":["type","person"],"additionalProperties":false},"offset_days":{"type":"integer"},"visible_days":{"type":"integer","nullable":true}},"required":["id","title","description","link_url","assignee","offset_days","visible_days"],"additionalProperties":false}},"archived":{"type":"boolean"},"saved":{"type":"boolean"},"updated_at":{"type":"string","nullable":true}},"required":["id","name","kind","auto_start","conditions","tasks","archived","saved","updated_at"],"additionalProperties":false}}},"required":["templates"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.checklists.templates.list","summary":"List checklist templates","description":"Lists the company's checklist templates (Settings → Checklists): onboarding (due dates relative to the start date), offboarding (relative to the last day) and custom (relative to a date chosen when starting). Each has auto_start (onboarding and offboarding start by themselves when someone is hired or terminated), conditions (unit_ids — a unit includes its subunits —, location_ids, legal_entity_ids; empty = everyone; lists combine with AND) and tasks (title, description, link_url, assignee: hr | manager | person | member with a person, offset_days: negative = before). Until the company changes anything, the two starter templates Bizisy ships are listed with saved=false. Archived templates only with include_archived. Owners, admins and HR.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"templates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"auto_start":{"type":"boolean"},"conditions":{"type":"object","properties":{"unit_ids":{"type":"array","items":{"type":"string"}},"location_ids":{"type":"array","items":{"type":"string"}},"legal_entity_ids":{"type":"array","items":{"type":"string"}}},"required":["unit_ids","location_ids","legal_entity_ids"],"additionalProperties":false},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"link_url":{"type":"string","nullable":true},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true}},"required":["type","person"],"additionalProperties":false},"offset_days":{"type":"integer"},"visible_days":{"type":"integer","nullable":true}},"required":["id","title","description","link_url","assignee","offset_days","visible_days"],"additionalProperties":false}},"archived":{"type":"boolean"},"saved":{"type":"boolean"},"updated_at":{"type":"string","nullable":true}},"required":["id","name","kind","auto_start","conditions","tasks","archived","saved","updated_at"],"additionalProperties":false}}},"required":["templates"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/checklists.templates.create":{"post":{"operationId":"org.checklists.templates.create","summary":"Create a checklist template","description":"Creates a checklist template: name, kind (onboarding, offboarding or custom), tasks (1–40: title, optional description and link_url (https), assignee {type: hr | manager | person | member, person_id only for member}, offset_days from -365 to 365 relative to the start date / last day / chosen date), optional conditions {unit_ids, location_ids, legal_entity_ids} and auto_start (default true for onboarding and offboarding; custom templates never start by themselves). \"hr\" means any owner, admin or HR member; \"manager\" is the person's manager when the checklist starts (HR if they have none); \"person\" is the person the checklist is about. A member assignee sees that task and whom it is about. Offboarding tasks show to the leaver and to member assignees only from visible_days (default 7) days before they are due. At most 30 active templates. Applies to checklists started from now on. Use dry_run first. Owners, admins and HR.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"auto_start":{"type":"boolean"},"conditions":{"type":"object","properties":{"unit_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50,"default":[]},"location_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50,"default":[]},"legal_entity_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50,"default":[]}},"additionalProperties":false},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z0-9_-]{1,40}$"},"title":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":1000,"nullable":true},"link_url":{"type":"string","maxLength":500,"nullable":true},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person_id":{"type":"string","minLength":1,"maxLength":100}},"required":["type"],"additionalProperties":false},"offset_days":{"type":"integer","minimum":-365,"maximum":365},"visible_days":{"type":"integer","minimum":0,"maximum":365,"nullable":true}},"required":["title","assignee","offset_days"],"additionalProperties":false},"minItems":1,"maxItems":40}},"required":["name","kind","tasks"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"auto_start":{"type":"boolean"},"conditions":{"type":"object","properties":{"unit_ids":{"type":"array","items":{"type":"string"}},"location_ids":{"type":"array","items":{"type":"string"}},"legal_entity_ids":{"type":"array","items":{"type":"string"}}},"required":["unit_ids","location_ids","legal_entity_ids"],"additionalProperties":false},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"link_url":{"type":"string","nullable":true},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true}},"required":["type","person"],"additionalProperties":false},"offset_days":{"type":"integer"},"visible_days":{"type":"integer","nullable":true}},"required":["id","title","description","link_url","assignee","offset_days","visible_days"],"additionalProperties":false}},"archived":{"type":"boolean"},"saved":{"type":"boolean"},"updated_at":{"type":"string","nullable":true}},"required":["id","name","kind","auto_start","conditions","tasks","archived","saved","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/checklists.templates.update":{"post":{"operationId":"org.checklists.templates.update","summary":"Change a checklist template","description":"Changes a checklist template (see org_checklists_templates_list for ids, including the starter templates): name, auto_start, conditions (replaces all three lists) and/or tasks (replaces the whole task list: send every task you want to keep, with its id; 1–40 tasks, same fields as org_checklists_templates_create). Checklists already running keep their tasks; only checklists started afterwards use the new version. Use dry_run first. Owners, admins and HR.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template_id":{"type":"string","minLength":1,"maxLength":100},"name":{"type":"string","minLength":1,"maxLength":80},"auto_start":{"type":"boolean"},"conditions":{"type":"object","properties":{"unit_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50,"default":[]},"location_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50,"default":[]},"legal_entity_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50,"default":[]}},"additionalProperties":false},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z0-9_-]{1,40}$"},"title":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":1000,"nullable":true},"link_url":{"type":"string","maxLength":500,"nullable":true},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person_id":{"type":"string","minLength":1,"maxLength":100}},"required":["type"],"additionalProperties":false},"offset_days":{"type":"integer","minimum":-365,"maximum":365},"visible_days":{"type":"integer","minimum":0,"maximum":365,"nullable":true}},"required":["title","assignee","offset_days"],"additionalProperties":false},"minItems":1,"maxItems":40}},"required":["template_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"auto_start":{"type":"boolean"},"conditions":{"type":"object","properties":{"unit_ids":{"type":"array","items":{"type":"string"}},"location_ids":{"type":"array","items":{"type":"string"}},"legal_entity_ids":{"type":"array","items":{"type":"string"}}},"required":["unit_ids","location_ids","legal_entity_ids"],"additionalProperties":false},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"link_url":{"type":"string","nullable":true},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true}},"required":["type","person"],"additionalProperties":false},"offset_days":{"type":"integer"},"visible_days":{"type":"integer","nullable":true}},"required":["id","title","description","link_url","assignee","offset_days","visible_days"],"additionalProperties":false}},"archived":{"type":"boolean"},"saved":{"type":"boolean"},"updated_at":{"type":"string","nullable":true}},"required":["id","name","kind","auto_start","conditions","tasks","archived","saved","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/checklists.templates.archive":{"post":{"operationId":"org.checklists.templates.archive","summary":"Archive or restore a checklist template","description":"Archives a checklist template (archived: true): it no longer starts by itself and cannot be started by hand; checklists already running are not affected. archived: false restores it. Templates are never deleted. Owners, admins and HR.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template_id":{"type":"string","minLength":1,"maxLength":100},"archived":{"type":"boolean"}},"required":["template_id","archived"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"auto_start":{"type":"boolean"},"conditions":{"type":"object","properties":{"unit_ids":{"type":"array","items":{"type":"string"}},"location_ids":{"type":"array","items":{"type":"string"}},"legal_entity_ids":{"type":"array","items":{"type":"string"}}},"required":["unit_ids","location_ids","legal_entity_ids"],"additionalProperties":false},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"link_url":{"type":"string","nullable":true},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true}},"required":["type","person"],"additionalProperties":false},"offset_days":{"type":"integer"},"visible_days":{"type":"integer","nullable":true}},"required":["id","title","description","link_url","assignee","offset_days","visible_days"],"additionalProperties":false}},"archived":{"type":"boolean"},"saved":{"type":"boolean"},"updated_at":{"type":"string","nullable":true}},"required":["id","name","kind","auto_start","conditions","tasks","archived","saved","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/checklists.runs.start":{"post":{"operationId":"org.checklists.runs.start","summary":"Start a checklist for a person","description":"Starts a checklist from a template (template_id from org_checklists_templates_list) for a person (person_id from org_people_list). Due dates hang off anchor_date: by default their start date (onboarding: the current or next employment), their last day (offboarding: they must have one, so terminate first) or today (custom). Pass anchor_date (YYYY-MM-DD) to use another date. Assignees are resolved now: the manager on that date (HR if none), the person, or the named member. Refused when an open checklist from the same template already runs for them, or when the template is archived. Onboarding and offboarding templates with auto_start also start by themselves on org_people_hire, org_people_rehire and org_people_terminate. Use dry_run first. Owners, admins and HR.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"person_id":{"type":"string","minLength":1,"maxLength":100},"template_id":{"type":"string","minLength":1,"maxLength":100},"anchor_date":{"type":"string"}},"required":["person_id","template_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"template_id":{"type":"string","nullable":true},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"anchor_date":{"type":"string","nullable":true},"anchor_source":{"type":"string","enum":["start","last_day","chosen"]},"status":{"type":"string","enum":["open","completed","cancelled"]},"started_by":{"type":"string","enum":["auto","manual"]},"started_at":{"type":"string"},"completed_at":{"type":"string","nullable":true},"cancelled_at":{"type":"string","nullable":true},"progress":{"type":"object","properties":{"done":{"type":"integer"},"skipped":{"type":"integer"},"total":{"type":"integer"}},"required":["done","skipped","total"],"additionalProperties":false,"nullable":true},"access":{"type":"string","enum":["full","assigned"]},"can_cancel":{"type":"boolean"},"shared_with_person":{"type":"boolean"},"can_share":{"type":"boolean"},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"link_url":{"type":"string","nullable":true},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true}},"required":["type","person"],"additionalProperties":false},"manager_missing":{"type":"boolean"},"offset_days":{"type":"integer"},"due_date":{"type":"string"},"visible_from":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","done","skipped"]},"resolved_at":{"type":"string","nullable":true},"resolved_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"skip_reason":{"type":"string","nullable":true},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"text":{"type":"string"},"at":{"type":"string"}},"required":["id","author","text","at"],"additionalProperties":false}},"can":{"type":"object","properties":{"tick":{"type":"boolean"},"skip":{"type":"boolean"},"reassign":{"type":"boolean"},"comment":{"type":"boolean"}},"required":["tick","skip","reassign","comment"],"additionalProperties":false}},"required":["id","title","description","link_url","assignee","manager_missing","offset_days","due_date","visible_from","status","resolved_at","resolved_by","skip_reason","comments","can"],"additionalProperties":false}}},"required":["id","name","kind","template_id","person","anchor_date","anchor_source","status","started_by","started_at","completed_at","cancelled_at","progress","access","can_cancel","shared_with_person","can_share","tasks"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/checklists.runs.cancel":{"post":{"operationId":"org.checklists.runs.cancel","summary":"Cancel a checklist","description":"Cancels a running (or completed) checklist: it stays visible with its ticked tasks but nothing can change any more and its tasks leave everyone’s lists and emails. Use it when a hire falls through or a checklist was started by mistake. Owners, admins and HR.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"string","minLength":1,"maxLength":100}},"required":["run_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"template_id":{"type":"string","nullable":true},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"anchor_date":{"type":"string","nullable":true},"anchor_source":{"type":"string","enum":["start","last_day","chosen"]},"status":{"type":"string","enum":["open","completed","cancelled"]},"started_by":{"type":"string","enum":["auto","manual"]},"started_at":{"type":"string"},"completed_at":{"type":"string","nullable":true},"cancelled_at":{"type":"string","nullable":true},"progress":{"type":"object","properties":{"done":{"type":"integer"},"skipped":{"type":"integer"},"total":{"type":"integer"}},"required":["done","skipped","total"],"additionalProperties":false,"nullable":true},"access":{"type":"string","enum":["full","assigned"]},"can_cancel":{"type":"boolean"},"shared_with_person":{"type":"boolean"},"can_share":{"type":"boolean"},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"link_url":{"type":"string","nullable":true},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true}},"required":["type","person"],"additionalProperties":false},"manager_missing":{"type":"boolean"},"offset_days":{"type":"integer"},"due_date":{"type":"string"},"visible_from":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","done","skipped"]},"resolved_at":{"type":"string","nullable":true},"resolved_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"skip_reason":{"type":"string","nullable":true},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"text":{"type":"string"},"at":{"type":"string"}},"required":["id","author","text","at"],"additionalProperties":false}},"can":{"type":"object","properties":{"tick":{"type":"boolean"},"skip":{"type":"boolean"},"reassign":{"type":"boolean"},"comment":{"type":"boolean"}},"required":["tick","skip","reassign","comment"],"additionalProperties":false}},"required":["id","title","description","link_url","assignee","manager_missing","offset_days","due_date","visible_from","status","resolved_at","resolved_by","skip_reason","comments","can"],"additionalProperties":false}}},"required":["id","name","kind","template_id","person","anchor_date","anchor_source","status","started_by","started_at","completed_at","cancelled_at","progress","access","can_cancel","shared_with_person","can_share","tasks"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/checklists.runs.share":{"post":{"operationId":"org.checklists.runs.share","summary":"Share an offboarding checklist with the person leaving","description":"Shares an offboarding checklist with the person it is about (shared: true): from then on they see their own tasks on it (for example \"Hand over your work\") in Me → My tasks and in their emails. Until it is shared, they only see each of their tasks from 7 days before it is due (or the number of days its template sets), since a last day is often recorded before it is announced. shared: false stops sharing. Member assignees outside HR and the manager chain always follow those visible-from dates. Owners, admins and HR.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"string","minLength":1,"maxLength":100},"shared":{"type":"boolean"}},"required":["run_id","shared"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"template_id":{"type":"string","nullable":true},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"anchor_date":{"type":"string","nullable":true},"anchor_source":{"type":"string","enum":["start","last_day","chosen"]},"status":{"type":"string","enum":["open","completed","cancelled"]},"started_by":{"type":"string","enum":["auto","manual"]},"started_at":{"type":"string"},"completed_at":{"type":"string","nullable":true},"cancelled_at":{"type":"string","nullable":true},"progress":{"type":"object","properties":{"done":{"type":"integer"},"skipped":{"type":"integer"},"total":{"type":"integer"}},"required":["done","skipped","total"],"additionalProperties":false,"nullable":true},"access":{"type":"string","enum":["full","assigned"]},"can_cancel":{"type":"boolean"},"shared_with_person":{"type":"boolean"},"can_share":{"type":"boolean"},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"link_url":{"type":"string","nullable":true},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true}},"required":["type","person"],"additionalProperties":false},"manager_missing":{"type":"boolean"},"offset_days":{"type":"integer"},"due_date":{"type":"string"},"visible_from":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","done","skipped"]},"resolved_at":{"type":"string","nullable":true},"resolved_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"skip_reason":{"type":"string","nullable":true},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"text":{"type":"string"},"at":{"type":"string"}},"required":["id","author","text","at"],"additionalProperties":false}},"can":{"type":"object","properties":{"tick":{"type":"boolean"},"skip":{"type":"boolean"},"reassign":{"type":"boolean"},"comment":{"type":"boolean"}},"required":["tick","skip","reassign","comment"],"additionalProperties":false}},"required":["id","title","description","link_url","assignee","manager_missing","offset_days","due_date","visible_from","status","resolved_at","resolved_by","skip_reason","comments","can"],"additionalProperties":false}}},"required":["id","name","kind","template_id","person","anchor_date","anchor_source","status","started_by","started_at","completed_at","cancelled_at","progress","access","can_cancel","shared_with_person","can_share","tasks"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/checklists.runs.list":{"post":{"operationId":"org.checklists.runs.list","summary":"List checklists","description":"Lists checklists (onboarding, offboarding, custom) with their progress (done, skipped, total) and tasks. person_id: only that person’s checklists. status: open, completed, cancelled or all (default: all with person_id, else open). Owners, admins, HR and the person’s managers see every task; the person themself and member assignees see only the tasks assigned to them (access \"assigned\"; a member assignee gets no date or progress for the checklist), and on offboarding only from each task’s visible_from date (the person sooner if HR shared it with them, org_checklists_runs_share); others see nothing. Each task says what you may do with it (can).","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"person_id":{"type":"string","minLength":1,"maxLength":100},"status":{"type":"string","enum":["open","completed","cancelled","all"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"today":{"type":"string"},"runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"template_id":{"type":"string","nullable":true},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"anchor_date":{"type":"string","nullable":true},"anchor_source":{"type":"string","enum":["start","last_day","chosen"]},"status":{"type":"string","enum":["open","completed","cancelled"]},"started_by":{"type":"string","enum":["auto","manual"]},"started_at":{"type":"string"},"completed_at":{"type":"string","nullable":true},"cancelled_at":{"type":"string","nullable":true},"progress":{"type":"object","properties":{"done":{"type":"integer"},"skipped":{"type":"integer"},"total":{"type":"integer"}},"required":["done","skipped","total"],"additionalProperties":false,"nullable":true},"access":{"type":"string","enum":["full","assigned"]},"can_cancel":{"type":"boolean"},"shared_with_person":{"type":"boolean"},"can_share":{"type":"boolean"},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"link_url":{"type":"string","nullable":true},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true}},"required":["type","person"],"additionalProperties":false},"manager_missing":{"type":"boolean"},"offset_days":{"type":"integer"},"due_date":{"type":"string"},"visible_from":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","done","skipped"]},"resolved_at":{"type":"string","nullable":true},"resolved_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"skip_reason":{"type":"string","nullable":true},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"text":{"type":"string"},"at":{"type":"string"}},"required":["id","author","text","at"],"additionalProperties":false}},"can":{"type":"object","properties":{"tick":{"type":"boolean"},"skip":{"type":"boolean"},"reassign":{"type":"boolean"},"comment":{"type":"boolean"}},"required":["tick","skip","reassign","comment"],"additionalProperties":false}},"required":["id","title","description","link_url","assignee","manager_missing","offset_days","due_date","visible_from","status","resolved_at","resolved_by","skip_reason","comments","can"],"additionalProperties":false}}},"required":["id","name","kind","template_id","person","anchor_date","anchor_source","status","started_by","started_at","completed_at","cancelled_at","progress","access","can_cancel","shared_with_person","can_share","tasks"],"additionalProperties":false}}},"required":["today","runs"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.checklists.runs.list","summary":"List checklists","description":"Lists checklists (onboarding, offboarding, custom) with their progress (done, skipped, total) and tasks. person_id: only that person’s checklists. status: open, completed, cancelled or all (default: all with person_id, else open). Owners, admins, HR and the person’s managers see every task; the person themself and member assignees see only the tasks assigned to them (access \"assigned\"; a member assignee gets no date or progress for the checklist), and on offboarding only from each task’s visible_from date (the person sooner if HR shared it with them, org_checklists_runs_share); others see nothing. Each task says what you may do with it (can).","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"today":{"type":"string"},"runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"template_id":{"type":"string","nullable":true},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false},"anchor_date":{"type":"string","nullable":true},"anchor_source":{"type":"string","enum":["start","last_day","chosen"]},"status":{"type":"string","enum":["open","completed","cancelled"]},"started_by":{"type":"string","enum":["auto","manual"]},"started_at":{"type":"string"},"completed_at":{"type":"string","nullable":true},"cancelled_at":{"type":"string","nullable":true},"progress":{"type":"object","properties":{"done":{"type":"integer"},"skipped":{"type":"integer"},"total":{"type":"integer"}},"required":["done","skipped","total"],"additionalProperties":false,"nullable":true},"access":{"type":"string","enum":["full","assigned"]},"can_cancel":{"type":"boolean"},"shared_with_person":{"type":"boolean"},"can_share":{"type":"boolean"},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"link_url":{"type":"string","nullable":true},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true}},"required":["type","person"],"additionalProperties":false},"manager_missing":{"type":"boolean"},"offset_days":{"type":"integer"},"due_date":{"type":"string"},"visible_from":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","done","skipped"]},"resolved_at":{"type":"string","nullable":true},"resolved_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"skip_reason":{"type":"string","nullable":true},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"text":{"type":"string"},"at":{"type":"string"}},"required":["id","author","text","at"],"additionalProperties":false}},"can":{"type":"object","properties":{"tick":{"type":"boolean"},"skip":{"type":"boolean"},"reassign":{"type":"boolean"},"comment":{"type":"boolean"}},"required":["tick","skip","reassign","comment"],"additionalProperties":false}},"required":["id","title","description","link_url","assignee","manager_missing","offset_days","due_date","visible_from","status","resolved_at","resolved_by","skip_reason","comments","can"],"additionalProperties":false}}},"required":["id","name","kind","template_id","person","anchor_date","anchor_source","status","started_by","started_at","completed_at","cancelled_at","progress","access","can_cancel","shared_with_person","can_share","tasks"],"additionalProperties":false}}},"required":["today","runs"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/checklists.tasks.list":{"post":{"operationId":"org.checklists.tasks.list","summary":"List checklist tasks","description":"Lists checklist tasks across people, soonest due first. scope: mine (default: tasks assigned to you, plus HR tasks if you are an owner, admin or HR), team (every task on the checklists of people who report to you, directly or further down) or all (owners, admins and HR only). status: open (default) or all (adds done and skipped tasks of running and completed checklists). due_by (YYYY-MM-DD): only tasks due on or before it, e.g. today for what is due or overdue. Each item carries its checklist (run) and the person it is about.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","enum":["mine","team","all"]},"status":{"type":"string","enum":["open","all"]},"due_by":{"type":"string"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"today":{"type":"string"},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"link_url":{"type":"string","nullable":true},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true}},"required":["type","person"],"additionalProperties":false},"manager_missing":{"type":"boolean"},"offset_days":{"type":"integer"},"due_date":{"type":"string"},"visible_from":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","done","skipped"]},"resolved_at":{"type":"string","nullable":true},"resolved_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"skip_reason":{"type":"string","nullable":true},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"text":{"type":"string"},"at":{"type":"string"}},"required":["id","author","text","at"],"additionalProperties":false}},"can":{"type":"object","properties":{"tick":{"type":"boolean"},"skip":{"type":"boolean"},"reassign":{"type":"boolean"},"comment":{"type":"boolean"}},"required":["tick","skip","reassign","comment"],"additionalProperties":false},"run":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"status":{"type":"string","enum":["open","completed","cancelled"]},"anchor_date":{"type":"string","nullable":true}},"required":["id","name","kind","status","anchor_date"],"additionalProperties":false},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"required":["id","title","description","link_url","assignee","manager_missing","offset_days","due_date","visible_from","status","resolved_at","resolved_by","skip_reason","comments","can","run","person"],"additionalProperties":false}}},"required":["today","tasks"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.checklists.tasks.list","summary":"List checklist tasks","description":"Lists checklist tasks across people, soonest due first. scope: mine (default: tasks assigned to you, plus HR tasks if you are an owner, admin or HR), team (every task on the checklists of people who report to you, directly or further down) or all (owners, admins and HR only). status: open (default) or all (adds done and skipped tasks of running and completed checklists). due_by (YYYY-MM-DD): only tasks due on or before it, e.g. today for what is due or overdue. Each item carries its checklist (run) and the person it is about.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"today":{"type":"string"},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"link_url":{"type":"string","nullable":true},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true}},"required":["type","person"],"additionalProperties":false},"manager_missing":{"type":"boolean"},"offset_days":{"type":"integer"},"due_date":{"type":"string"},"visible_from":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","done","skipped"]},"resolved_at":{"type":"string","nullable":true},"resolved_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"skip_reason":{"type":"string","nullable":true},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"text":{"type":"string"},"at":{"type":"string"}},"required":["id","author","text","at"],"additionalProperties":false}},"can":{"type":"object","properties":{"tick":{"type":"boolean"},"skip":{"type":"boolean"},"reassign":{"type":"boolean"},"comment":{"type":"boolean"}},"required":["tick","skip","reassign","comment"],"additionalProperties":false},"run":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"status":{"type":"string","enum":["open","completed","cancelled"]},"anchor_date":{"type":"string","nullable":true}},"required":["id","name","kind","status","anchor_date"],"additionalProperties":false},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"required":["id","title","description","link_url","assignee","manager_missing","offset_days","due_date","visible_from","status","resolved_at","resolved_by","skip_reason","comments","can","run","person"],"additionalProperties":false}}},"required":["today","tasks"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/checklists.tasks.set_status":{"post":{"operationId":"org.checklists.tasks.set_status","summary":"Tick, untick or skip a checklist task","description":"Sets a task’s status: done (tick), open (untick or undo a skip) or skipped (with a reason, up to 200 characters, e.g. \"Already has a laptop\"). The checklist completes by itself when no task is open, and reopens when one is unticked. The assignee (and HR for HR tasks) can tick and untick; skipping, and undoing a skip, is for owners, admins, HR and the person’s managers. Cancelled checklists cannot change. Use run_id and task_id from org_checklists_tasks_list or org_checklists_runs_list.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"string","minLength":1,"maxLength":100},"task_id":{"type":"string","minLength":1,"maxLength":100},"status":{"type":"string","enum":["open","done","skipped"]},"reason":{"type":"string","minLength":1,"maxLength":200}},"required":["run_id","task_id","status"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"link_url":{"type":"string","nullable":true},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true}},"required":["type","person"],"additionalProperties":false},"manager_missing":{"type":"boolean"},"offset_days":{"type":"integer"},"due_date":{"type":"string"},"visible_from":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","done","skipped"]},"resolved_at":{"type":"string","nullable":true},"resolved_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"skip_reason":{"type":"string","nullable":true},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"text":{"type":"string"},"at":{"type":"string"}},"required":["id","author","text","at"],"additionalProperties":false}},"can":{"type":"object","properties":{"tick":{"type":"boolean"},"skip":{"type":"boolean"},"reassign":{"type":"boolean"},"comment":{"type":"boolean"}},"required":["tick","skip","reassign","comment"],"additionalProperties":false},"run":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"status":{"type":"string","enum":["open","completed","cancelled"]},"anchor_date":{"type":"string","nullable":true}},"required":["id","name","kind","status","anchor_date"],"additionalProperties":false},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"required":["id","title","description","link_url","assignee","manager_missing","offset_days","due_date","visible_from","status","resolved_at","resolved_by","skip_reason","comments","can","run","person"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/checklists.tasks.reassign":{"post":{"operationId":"org.checklists.tasks.reassign","summary":"Reassign a checklist task","description":"Gives a task to someone else: assignee {type: hr} (any owner, admin or HR member), {type: manager} (the person’s manager today), {type: person} (the person the checklist is about) or {type: member, person_id} (any current employee; they will see this task and whom it is about). Owners, admins, HR and the person’s managers. Cancelled checklists cannot change.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"string","minLength":1,"maxLength":100},"task_id":{"type":"string","minLength":1,"maxLength":100},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person_id":{"type":"string","minLength":1,"maxLength":100}},"required":["type"],"additionalProperties":false}},"required":["run_id","task_id","assignee"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"link_url":{"type":"string","nullable":true},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true}},"required":["type","person"],"additionalProperties":false},"manager_missing":{"type":"boolean"},"offset_days":{"type":"integer"},"due_date":{"type":"string"},"visible_from":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","done","skipped"]},"resolved_at":{"type":"string","nullable":true},"resolved_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"skip_reason":{"type":"string","nullable":true},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"text":{"type":"string"},"at":{"type":"string"}},"required":["id","author","text","at"],"additionalProperties":false}},"can":{"type":"object","properties":{"tick":{"type":"boolean"},"skip":{"type":"boolean"},"reassign":{"type":"boolean"},"comment":{"type":"boolean"}},"required":["tick","skip","reassign","comment"],"additionalProperties":false},"run":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"status":{"type":"string","enum":["open","completed","cancelled"]},"anchor_date":{"type":"string","nullable":true}},"required":["id","name","kind","status","anchor_date"],"additionalProperties":false},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"required":["id","title","description","link_url","assignee","manager_missing","offset_days","due_date","visible_from","status","resolved_at","resolved_by","skip_reason","comments","can","run","person"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/checklists.tasks.comment":{"post":{"operationId":"org.checklists.tasks.comment","summary":"Comment on a checklist task","description":"Adds a comment (up to 1000 characters) to a task, e.g. \"Laptop ordered, arrives Tuesday\". Everyone who sees the task sees its comments, with your name and the time. At most 50 comments per task; comments cannot be edited. The assignee, owners, admins, HR and the person’s managers can comment. Do not put health or other sensitive details in comments.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"string","minLength":1,"maxLength":100},"task_id":{"type":"string","minLength":1,"maxLength":100},"text":{"type":"string","minLength":1,"maxLength":1000}},"required":["run_id","task_id","text"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"link_url":{"type":"string","nullable":true},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["hr","manager","person","member"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true}},"required":["type","person"],"additionalProperties":false},"manager_missing":{"type":"boolean"},"offset_days":{"type":"integer"},"due_date":{"type":"string"},"visible_from":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","done","skipped"]},"resolved_at":{"type":"string","nullable":true},"resolved_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"skip_reason":{"type":"string","nullable":true},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false,"nullable":true},"text":{"type":"string"},"at":{"type":"string"}},"required":["id","author","text","at"],"additionalProperties":false}},"can":{"type":"object","properties":{"tick":{"type":"boolean"},"skip":{"type":"boolean"},"reassign":{"type":"boolean"},"comment":{"type":"boolean"}},"required":["tick","skip","reassign","comment"],"additionalProperties":false},"run":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["onboarding","offboarding","custom"]},"status":{"type":"string","enum":["open","completed","cancelled"]},"anchor_date":{"type":"string","nullable":true}},"required":["id","name","kind","status","anchor_date"],"additionalProperties":false},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true}},"required":["id","name","title","photo_url"],"additionalProperties":false}},"required":["id","title","description","link_url","assignee","manager_missing","offset_days","due_date","visible_from","status","resolved_at","resolved_by","skip_reason","comments","can","run","person"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/checklists.settings.get":{"post":{"operationId":"org.checklists.settings.get","summary":"Get checklist settings","description":"Returns the checklist settings: email_tasks (default true) — whether the daily reminder email tells each assignee about their checklist tasks on the due date and then once a week while they stay open. Owners, admins and HR.","tags":["org"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"email_tasks":{"type":"boolean"},"updated_at":{"type":"string","nullable":true}},"required":["email_tasks","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"org.checklists.settings.get","summary":"Get checklist settings","description":"Returns the checklist settings: email_tasks (default true) — whether the daily reminder email tells each assignee about their checklist tasks on the due date and then once a week while they stay open. Owners, admins and HR.","tags":["org"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"email_tasks":{"type":"boolean"},"updated_at":{"type":"string","nullable":true}},"required":["email_tasks","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/org/checklists.settings.update":{"post":{"operationId":"org.checklists.settings.update","summary":"Change checklist settings","description":"Turns the checklist task emails on or off (email_tasks). On: the daily reminder email lists each assignee’s due and overdue checklist tasks (on the due date, then once a week while open); HR tasks go to every owner, admin and HR member. Applies from the next daily run. Owners, admins and HR.","tags":["org"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email_tasks":{"type":"boolean"}},"required":["email_tasks"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"email_tasks":{"type":"boolean"},"updated_at":{"type":"string","nullable":true}},"required":["email_tasks","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/documents/list":{"post":{"operationId":"documents.list","summary":"List documents","description":"Lists documents you can see, newest first (or largest first with sort=largest): person documents (contracts, addenda, certificates, ID copies…) and company documents (handbook, policies…). Filters: person_id (one person's documents), scope (person, company or all), category, q (words in the title). Owners, admins and HR see every document; others see the company documents shared with them and their own. Person documents are private: through an API key or an AI assistant, other people's documents come as metadata only (title, category, date, size; access = metadata), never their contents.","tags":["documents"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"person_id":{"type":"string","minLength":1},"scope":{"type":"string","enum":["person","company","all"],"description":"Default all (person_id implies person)."},"category":{"type":"string","maxLength":60},"q":{"type":"string","maxLength":100,"description":"Words that must all appear in the title (case-insensitive)."},"sort":{"type":"string","enum":["newest","largest"]},"limit":{"type":"integer","minimum":1,"maximum":500,"description":"Default 500."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"subject":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["person"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true}},"required":["kind","person"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["company"]}},"required":["kind"],"additionalProperties":false}]},"visibility":{"type":"string","enum":["hr","hr_person","hr_person_manager","everyone","managers","hr"]},"uploaded_by":{"type":"string","enum":["hr","self"],"description":"self: the person added it themself (\"From me\", or a custom field they fill in)."},"field":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"],"additionalProperties":false,"nullable":true,"description":"A custom file field's file (org_fields_list): its visibility follows the field's tier; replace or remove it through the field."},"expires_on":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true,"description":"null when you only see metadata."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The original file name; null when you only see metadata."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false},"access":{"type":"string","enum":["full","metadata"],"description":"metadata: title, category, date and size only (no notes, no download): API keys and AI assistants never get the contents of other people's documents."},"status":{"type":"string","enum":["pending","ready"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","category","subject","visibility","uploaded_by","field","expires_on","notes","file","access","status","created_at","updated_at"],"additionalProperties":false}},"categories":{"type":"array","items":{"type":"string"},"description":"Every category in use for new documents: the starter list and your own."},"max_file_bytes":{"type":"integer","description":"The largest file allowed (Settings → Storage)."}},"required":["documents","categories","max_file_bytes"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"documents.list","summary":"List documents","description":"Lists documents you can see, newest first (or largest first with sort=largest): person documents (contracts, addenda, certificates, ID copies…) and company documents (handbook, policies…). Filters: person_id (one person's documents), scope (person, company or all), category, q (words in the title). Owners, admins and HR see every document; others see the company documents shared with them and their own. Person documents are private: through an API key or an AI assistant, other people's documents come as metadata only (title, category, date, size; access = metadata), never their contents.","tags":["documents"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"subject":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["person"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true}},"required":["kind","person"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["company"]}},"required":["kind"],"additionalProperties":false}]},"visibility":{"type":"string","enum":["hr","hr_person","hr_person_manager","everyone","managers","hr"]},"uploaded_by":{"type":"string","enum":["hr","self"],"description":"self: the person added it themself (\"From me\", or a custom field they fill in)."},"field":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"],"additionalProperties":false,"nullable":true,"description":"A custom file field's file (org_fields_list): its visibility follows the field's tier; replace or remove it through the field."},"expires_on":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true,"description":"null when you only see metadata."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The original file name; null when you only see metadata."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false},"access":{"type":"string","enum":["full","metadata"],"description":"metadata: title, category, date and size only (no notes, no download): API keys and AI assistants never get the contents of other people's documents."},"status":{"type":"string","enum":["pending","ready"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","category","subject","visibility","uploaded_by","field","expires_on","notes","file","access","status","created_at","updated_at"],"additionalProperties":false}},"categories":{"type":"array","items":{"type":"string"},"description":"Every category in use for new documents: the starter list and your own."},"max_file_bytes":{"type":"integer","description":"The largest file allowed (Settings → Storage)."}},"required":["documents","categories","max_file_bytes"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/documents/upload.start":{"post":{"operationId":"documents.upload.start","summary":"Start a document upload","description":"Adds a document in two calls and one upload: (1) this call with the subject (a person, or the company), category, optional title (default: the file name), visibility, expires_on and notes, and the file's name, size, content_type and sha256; (2) PUT the file's bytes to the returned signed URL within 15 minutes, with exactly the returned headers (the size is part of them); (3) documents_upload_finish with the document id. Person document visibility: hr (owners, admins, HR), hr_person (default; also the person) or hr_person_manager (also their managers). Company: everyone (default), managers (people with reports and HR) or hr. Accepted: PDF, PNG, JPEG, WebP, HEIC, DOCX, XLSX, ODT, ODS, TXT, CSV (checked from the bytes; macros, archives and executables are refused); the largest file and the company's storage ceiling are set in Settings → Storage. Above 500 MB a company pays €1 per GB per month. Owners, admins and HR.","tags":["documents"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["person"]},"person_id":{"type":"string","minLength":1}},"required":["kind","person_id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["company"]}},"required":["kind"],"additionalProperties":false}]},"category":{"type":"string","minLength":1,"maxLength":40},"title":{"type":"string","maxLength":200},"visibility":{"type":"string","enum":["hr","hr_person","hr_person_manager","everyone","managers","hr"]},"expires_on":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"notes":{"type":"string","maxLength":2000,"nullable":true},"file":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":500,"description":"The file name, e.g. \"Contract 2026.pdf\" (kept as metadata only)."},"size":{"type":"integer","exclusiveMinimum":true,"minimum":0,"description":"Bytes. Must equal what is uploaded."},"content_type":{"type":"string","minLength":1,"maxLength":200,"description":"application/pdf, image/png, image/jpeg, image/webp, image/heic, DOCX, XLSX, ODT or ODS MIME type, text/plain or text/csv. Must match the bytes."},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Lowercase hex SHA-256 of the file; checked against the upload."}},"required":["name","size","content_type","sha256"],"additionalProperties":false}},"required":["subject","category","file"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"subject":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["person"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true}},"required":["kind","person"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["company"]}},"required":["kind"],"additionalProperties":false}]},"visibility":{"type":"string","enum":["hr","hr_person","hr_person_manager","everyone","managers","hr"]},"uploaded_by":{"type":"string","enum":["hr","self"],"description":"self: the person added it themself (\"From me\", or a custom field they fill in)."},"field":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"],"additionalProperties":false,"nullable":true,"description":"A custom file field's file (org_fields_list): its visibility follows the field's tier; replace or remove it through the field."},"expires_on":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true,"description":"null when you only see metadata."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The original file name; null when you only see metadata."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false},"access":{"type":"string","enum":["full","metadata"],"description":"metadata: title, category, date and size only (no notes, no download): API keys and AI assistants never get the contents of other people's documents."},"status":{"type":"string","enum":["pending","ready"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","category","subject","visibility","uploaded_by","field","expires_on","notes","file","access","status","created_at","updated_at"],"additionalProperties":false},"upload":{"type":"object","properties":{"url":{"type":"string","description":"Short-lived signed URL (15 minutes). Never share it."},"method":{"type":"string","enum":["PUT"]},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Send exactly these headers (they include the exact file size: any other size is refused)."},"resumable":{"type":"boolean","enum":[false],"description":"Always false: upload the whole file in one PUT."}},"required":["url","method","headers","resumable"],"additionalProperties":false,"nullable":true,"description":"null on a dry run."},"upload_expires_at":{"type":"string"}},"required":["document","upload","upload_expires_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/documents/upload.finish":{"post":{"operationId":"documents.upload.finish","summary":"Finish a document upload","description":"Finishes an upload started with documents_upload_start, after the bytes were uploaded: Bizisy checks the size, the SHA-256 and the type from the bytes, then the document appears for everyone its visibility allows. A file that does not match is deleted and refused (start again). Finishing twice returns the document. Owners, admins and HR.","tags":["documents"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"document_id":{"type":"string","minLength":1}},"required":["document_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"subject":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["person"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true}},"required":["kind","person"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["company"]}},"required":["kind"],"additionalProperties":false}]},"visibility":{"type":"string","enum":["hr","hr_person","hr_person_manager","everyone","managers","hr"]},"uploaded_by":{"type":"string","enum":["hr","self"],"description":"self: the person added it themself (\"From me\", or a custom field they fill in)."},"field":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"],"additionalProperties":false,"nullable":true,"description":"A custom file field's file (org_fields_list): its visibility follows the field's tier; replace or remove it through the field."},"expires_on":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true,"description":"null when you only see metadata."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The original file name; null when you only see metadata."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false},"access":{"type":"string","enum":["full","metadata"],"description":"metadata: title, category, date and size only (no notes, no download): API keys and AI assistants never get the contents of other people's documents."},"status":{"type":"string","enum":["pending","ready"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","category","subject","visibility","uploaded_by","field","expires_on","notes","file","access","status","created_at","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/documents/update":{"post":{"operationId":"documents.update","summary":"Change a document","description":"Changes a document's title, category, visibility, expiry date (expires_on, YYYY-MM-DD or null) or notes. Send only what changes. The visibility of a person's own \"From me\" upload stays hr_person; a custom field's file (field set) keeps the field's visibility and category (change the field instead). Owners, admins and HR.","tags":["documents"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"document_id":{"type":"string","minLength":1},"title":{"type":"string","minLength":1,"maxLength":200},"category":{"type":"string","minLength":1,"maxLength":40},"visibility":{"type":"string","enum":["hr","hr_person","hr_person_manager","everyone","managers","hr"]},"expires_on":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"notes":{"type":"string","maxLength":2000,"nullable":true}},"required":["document_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"subject":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["person"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true}},"required":["kind","person"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["company"]}},"required":["kind"],"additionalProperties":false}]},"visibility":{"type":"string","enum":["hr","hr_person","hr_person_manager","everyone","managers","hr"]},"uploaded_by":{"type":"string","enum":["hr","self"],"description":"self: the person added it themself (\"From me\", or a custom field they fill in)."},"field":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"],"additionalProperties":false,"nullable":true,"description":"A custom file field's file (org_fields_list): its visibility follows the field's tier; replace or remove it through the field."},"expires_on":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true,"description":"null when you only see metadata."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The original file name; null when you only see metadata."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false},"access":{"type":"string","enum":["full","metadata"],"description":"metadata: title, category, date and size only (no notes, no download): API keys and AI assistants never get the contents of other people's documents."},"status":{"type":"string","enum":["pending","ready"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","category","subject","visibility","uploaded_by","field","expires_on","notes","file","access","status","created_at","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/documents/delete":{"post":{"operationId":"documents.delete","summary":"Delete a document","description":"Deletes a document and its file for good (no recycle bin; the storage it used is freed, though this month's billed peak does not go down). A custom field's file (field set) is removed from the field too. Owners, admins and HR.","tags":["documents"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"document_id":{"type":"string","minLength":1}},"required":["document_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]},"category":{"type":"string"},"person_id":{"type":"string","nullable":true},"visibility":{"type":"string"}},"required":["id","deleted","category","person_id","visibility"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/documents/download":{"post":{"operationId":"documents.download","summary":"Download a document","description":"Returns a short-lived link (5 minutes) that downloads the document as a file. Downloading a person's document is recorded in Activity (company documents are not). Only for documents you can fully see: through an API key or an AI assistant, other people's documents never download. The link is never stored; ask again for a new one.","tags":["documents"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"document_id":{"type":"string","minLength":1}},"required":["document_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"url":{"type":"string","nullable":true,"description":"Signed URL valid for 5 minutes, downloads as an attachment. null on a dry run. Never store or share it."},"expires_at":{"type":"string","nullable":true},"file_name":{"type":"string"},"content_type":{"type":"string"},"size":{"type":"integer"},"category":{"type":"string"},"person_id":{"type":"string","nullable":true},"visibility":{"type":"string"}},"required":["url","expires_at","file_name","content_type","size","category","person_id","visibility"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/documents/categories.get":{"post":{"operationId":"documents.categories.get","summary":"See document categories","description":"The document categories: the starter list (Contract, Addendum, Certificate, ID, Policy, Handbook, Other) and your own.","tags":["documents"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"starter":{"type":"array","items":{"type":"string"}},"custom":{"type":"array","items":{"type":"string"}}},"required":["starter","custom"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"documents.categories.get","summary":"See document categories","description":"The document categories: the starter list (Contract, Addendum, Certificate, ID, Policy, Handbook, Other) and your own.","tags":["documents"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"starter":{"type":"array","items":{"type":"string"}},"custom":{"type":"array","items":{"type":"string"}}},"required":["starter","custom"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/documents/categories.set":{"post":{"operationId":"documents.categories.set","summary":"Change document categories","description":"Replaces your own document categories (up to 30, each up to 40 characters) beside the starter list. Documents keep the category they have when one is removed. Owners, admins and HR.","tags":["documents"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"custom":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"maxItems":30}},"required":["custom"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"starter":{"type":"array","items":{"type":"string"}},"custom":{"type":"array","items":{"type":"string"}}},"required":["starter","custom"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/documents/me.list":{"post":{"operationId":"documents.me.list","summary":"List my documents","description":"Lists documents shared with you, newest first. scope mine (default): your own documents (shared with you by HR, and the ones you added \"From me\"); company: company documents for you (handbook, policies…); person_id: documents of someone who reports to you that HR shared with their managers. Also says whether you can add your own documents this month (self_upload).","tags":["documents"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","enum":["mine","company"]},"person_id":{"type":"string","minLength":1}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"subject":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["person"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true}},"required":["kind","person"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["company"]}},"required":["kind"],"additionalProperties":false}]},"visibility":{"type":"string","enum":["hr","hr_person","hr_person_manager","everyone","managers","hr"]},"uploaded_by":{"type":"string","enum":["hr","self"],"description":"self: the person added it themself (\"From me\", or a custom field they fill in)."},"field":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"],"additionalProperties":false,"nullable":true,"description":"A custom file field's file (org_fields_list): its visibility follows the field's tier; replace or remove it through the field."},"expires_on":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true,"description":"null when you only see metadata."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The original file name; null when you only see metadata."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false},"access":{"type":"string","enum":["full","metadata"],"description":"metadata: title, category, date and size only (no notes, no download): API keys and AI assistants never get the contents of other people's documents."},"status":{"type":"string","enum":["pending","ready"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","category","subject","visibility","uploaded_by","field","expires_on","notes","file","access","status","created_at","updated_at"],"additionalProperties":false}},"categories":{"type":"array","items":{"type":"string"}},"self_upload":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Your company lets people add their own documents (\"From me\")."},"files_left":{"type":"integer","description":"Files you can still add this month."},"bytes_left":{"type":"integer","description":"Bytes you can still add this month."},"max_file_bytes":{"type":"integer","description":"The largest file allowed."}},"required":["enabled","files_left","bytes_left","max_file_bytes"],"additionalProperties":false,"nullable":true,"description":"null when your login is not linked to a person."}},"required":["documents","categories","self_upload"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"documents.me.list","summary":"List my documents","description":"Lists documents shared with you, newest first. scope mine (default): your own documents (shared with you by HR, and the ones you added \"From me\"); company: company documents for you (handbook, policies…); person_id: documents of someone who reports to you that HR shared with their managers. Also says whether you can add your own documents this month (self_upload).","tags":["documents"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"subject":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["person"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true}},"required":["kind","person"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["company"]}},"required":["kind"],"additionalProperties":false}]},"visibility":{"type":"string","enum":["hr","hr_person","hr_person_manager","everyone","managers","hr"]},"uploaded_by":{"type":"string","enum":["hr","self"],"description":"self: the person added it themself (\"From me\", or a custom field they fill in)."},"field":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"],"additionalProperties":false,"nullable":true,"description":"A custom file field's file (org_fields_list): its visibility follows the field's tier; replace or remove it through the field."},"expires_on":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true,"description":"null when you only see metadata."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The original file name; null when you only see metadata."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false},"access":{"type":"string","enum":["full","metadata"],"description":"metadata: title, category, date and size only (no notes, no download): API keys and AI assistants never get the contents of other people's documents."},"status":{"type":"string","enum":["pending","ready"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","category","subject","visibility","uploaded_by","field","expires_on","notes","file","access","status","created_at","updated_at"],"additionalProperties":false}},"categories":{"type":"array","items":{"type":"string"}},"self_upload":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Your company lets people add their own documents (\"From me\")."},"files_left":{"type":"integer","description":"Files you can still add this month."},"bytes_left":{"type":"integer","description":"Bytes you can still add this month."},"max_file_bytes":{"type":"integer","description":"The largest file allowed."}},"required":["enabled","files_left","bytes_left","max_file_bytes"],"additionalProperties":false,"nullable":true,"description":"null when your login is not linked to a person."}},"required":["documents","categories","self_upload"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/documents/me.download":{"post":{"operationId":"documents.me.download","summary":"Download a document","description":"Returns a short-lived link (5 minutes) that downloads a document shared with you as a file. Downloading a person document is recorded in Activity. The link is never stored; ask again for a new one.","tags":["documents"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"document_id":{"type":"string","minLength":1}},"required":["document_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"url":{"type":"string","nullable":true,"description":"Signed URL valid for 5 minutes, downloads as an attachment. null on a dry run. Never store or share it."},"expires_at":{"type":"string","nullable":true},"file_name":{"type":"string"},"content_type":{"type":"string"},"size":{"type":"integer"},"category":{"type":"string"},"person_id":{"type":"string","nullable":true}},"required":["url","expires_at","file_name","content_type","size","category","person_id"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/documents/me.upload.start":{"post":{"operationId":"documents.me.upload.start","summary":"Add my own document","description":"Adds a document to your \"From me\" folder in two calls and one upload (like documents_upload_start): this call with the category, optional title and expiry date and the file's name, size, content_type and sha256; PUT the bytes to the signed URL within 15 minutes with exactly the returned headers; then documents_me_upload_finish. Only you and your HR team (owners, admins, HR) see it; HR is emailed when it arrives. Limits: the largest file, and per month a number of files and MB set by your company (see documents_me_list self_upload).","tags":["documents"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","minLength":1,"maxLength":40,"description":"Default Other."},"title":{"type":"string","maxLength":200},"expires_on":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"file":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":500,"description":"The file name, e.g. \"Contract 2026.pdf\" (kept as metadata only)."},"size":{"type":"integer","exclusiveMinimum":true,"minimum":0,"description":"Bytes. Must equal what is uploaded."},"content_type":{"type":"string","minLength":1,"maxLength":200,"description":"application/pdf, image/png, image/jpeg, image/webp, image/heic, DOCX, XLSX, ODT or ODS MIME type, text/plain or text/csv. Must match the bytes."},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Lowercase hex SHA-256 of the file; checked against the upload."}},"required":["name","size","content_type","sha256"],"additionalProperties":false}},"required":["file"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"subject":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["person"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true}},"required":["kind","person"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["company"]}},"required":["kind"],"additionalProperties":false}]},"visibility":{"type":"string","enum":["hr","hr_person","hr_person_manager","everyone","managers","hr"]},"uploaded_by":{"type":"string","enum":["hr","self"],"description":"self: the person added it themself (\"From me\", or a custom field they fill in)."},"field":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"],"additionalProperties":false,"nullable":true,"description":"A custom file field's file (org_fields_list): its visibility follows the field's tier; replace or remove it through the field."},"expires_on":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true,"description":"null when you only see metadata."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The original file name; null when you only see metadata."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false},"access":{"type":"string","enum":["full","metadata"],"description":"metadata: title, category, date and size only (no notes, no download): API keys and AI assistants never get the contents of other people's documents."},"status":{"type":"string","enum":["pending","ready"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","category","subject","visibility","uploaded_by","field","expires_on","notes","file","access","status","created_at","updated_at"],"additionalProperties":false},"upload":{"type":"object","properties":{"url":{"type":"string","description":"Short-lived signed URL (15 minutes). Never share it."},"method":{"type":"string","enum":["PUT"]},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Send exactly these headers (they include the exact file size: any other size is refused)."},"resumable":{"type":"boolean","enum":[false],"description":"Always false: upload the whole file in one PUT."}},"required":["url","method","headers","resumable"],"additionalProperties":false,"nullable":true},"upload_expires_at":{"type":"string"}},"required":["document","upload","upload_expires_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/documents/me.upload.finish":{"post":{"operationId":"documents.me.upload.finish","summary":"Finish adding my document","description":"Finishes your \"From me\" upload after the bytes were uploaded: Bizisy checks the file (size, SHA-256, type from the bytes) and your monthly limits, then it appears in My documents and your HR team is emailed (the email never includes the file name). Finishing twice returns the document.","tags":["documents"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"document_id":{"type":"string","minLength":1}},"required":["document_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"subject":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["person"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true}},"required":["kind","person"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["company"]}},"required":["kind"],"additionalProperties":false}]},"visibility":{"type":"string","enum":["hr","hr_person","hr_person_manager","everyone","managers","hr"]},"uploaded_by":{"type":"string","enum":["hr","self"],"description":"self: the person added it themself (\"From me\", or a custom field they fill in)."},"field":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"],"additionalProperties":false,"nullable":true,"description":"A custom file field's file (org_fields_list): its visibility follows the field's tier; replace or remove it through the field."},"expires_on":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true,"description":"null when you only see metadata."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The original file name; null when you only see metadata."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false},"access":{"type":"string","enum":["full","metadata"],"description":"metadata: title, category, date and size only (no notes, no download): API keys and AI assistants never get the contents of other people's documents."},"status":{"type":"string","enum":["pending","ready"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","category","subject","visibility","uploaded_by","field","expires_on","notes","file","access","status","created_at","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/documents/field_file.start":{"post":{"operationId":"documents.field_file.start","summary":"Start a file upload for a person's file field","description":"Puts a file in a custom field of type file (org_fields_list: type file) for a person, in two calls and one upload: (1) this call with person_id, field_key and the file's name, size, content_type and sha256; (2) PUT the bytes to the returned signed URL within 15 minutes with exactly the returned headers; (3) documents_field_file_finish with the document id. The field keeps one file: finishing replaces the one it had (deleted). Accepted: the field's kinds (pdf, image, office) up to the smaller of the field's max_mb and the company's largest file; archived fields are refused. The file is a person document (listed in their Documents, from the field) and follows the field's tier: private = the person and HR, job = also their managers, public = everyone in the company; API keys and AI assistants never get other people's files. Owners, admins and HR.","tags":["documents"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"person_id":{"type":"string","minLength":1},"field_key":{"type":"string","minLength":1,"maxLength":40,"description":"The file field's key (org_fields_list, type file)."},"file":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":500,"description":"The file name, e.g. \"Contract 2026.pdf\" (kept as metadata only)."},"size":{"type":"integer","exclusiveMinimum":true,"minimum":0,"description":"Bytes. Must equal what is uploaded."},"content_type":{"type":"string","minLength":1,"maxLength":200,"description":"application/pdf, image/png, image/jpeg, image/webp, image/heic, DOCX, XLSX, ODT or ODS MIME type, text/plain or text/csv. Must match the bytes."},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Lowercase hex SHA-256 of the file; checked against the upload."}},"required":["name","size","content_type","sha256"],"additionalProperties":false}},"required":["person_id","field_key","file"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"subject":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["person"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true}},"required":["kind","person"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["company"]}},"required":["kind"],"additionalProperties":false}]},"visibility":{"type":"string","enum":["hr","hr_person","hr_person_manager","everyone","managers","hr"]},"uploaded_by":{"type":"string","enum":["hr","self"],"description":"self: the person added it themself (\"From me\", or a custom field they fill in)."},"field":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"],"additionalProperties":false,"nullable":true,"description":"A custom file field's file (org_fields_list): its visibility follows the field's tier; replace or remove it through the field."},"expires_on":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true,"description":"null when you only see metadata."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The original file name; null when you only see metadata."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false},"access":{"type":"string","enum":["full","metadata"],"description":"metadata: title, category, date and size only (no notes, no download): API keys and AI assistants never get the contents of other people's documents."},"status":{"type":"string","enum":["pending","ready"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","category","subject","visibility","uploaded_by","field","expires_on","notes","file","access","status","created_at","updated_at"],"additionalProperties":false},"upload":{"type":"object","properties":{"url":{"type":"string","description":"Short-lived signed URL (15 minutes). Never share it."},"method":{"type":"string","enum":["PUT"]},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Send exactly these headers (they include the exact file size: any other size is refused)."},"resumable":{"type":"boolean","enum":[false],"description":"Always false: upload the whole file in one PUT."}},"required":["url","method","headers","resumable"],"additionalProperties":false,"nullable":true,"description":"null on a dry run."},"upload_expires_at":{"type":"string"}},"required":["document","upload","upload_expires_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/documents/field_file.finish":{"post":{"operationId":"documents.field_file.finish","summary":"Finish a person's file field upload","description":"Finishes an upload started with documents_field_file_start, after the bytes were uploaded: Bizisy checks the size, SHA-256 and type from the bytes, the field now holds the file, and the file it held before is deleted. A file that does not match is deleted and refused (start again). Finishing twice returns the document. Owners, admins and HR.","tags":["documents"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"document_id":{"type":"string","minLength":1}},"required":["document_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"subject":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["person"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true}},"required":["kind","person"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["company"]}},"required":["kind"],"additionalProperties":false}]},"visibility":{"type":"string","enum":["hr","hr_person","hr_person_manager","everyone","managers","hr"]},"uploaded_by":{"type":"string","enum":["hr","self"],"description":"self: the person added it themself (\"From me\", or a custom field they fill in)."},"field":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"],"additionalProperties":false,"nullable":true,"description":"A custom file field's file (org_fields_list): its visibility follows the field's tier; replace or remove it through the field."},"expires_on":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true,"description":"null when you only see metadata."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The original file name; null when you only see metadata."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false},"access":{"type":"string","enum":["full","metadata"],"description":"metadata: title, category, date and size only (no notes, no download): API keys and AI assistants never get the contents of other people's documents."},"status":{"type":"string","enum":["pending","ready"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","category","subject","visibility","uploaded_by","field","expires_on","notes","file","access","status","created_at","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/documents/me.field_file.start":{"post":{"operationId":"documents.me.field_file.start","summary":"Start uploading my file for a field","description":"Puts your own file in one of your custom fields of type file that your company lets people fill in (org_fields_list: type file, file.self_upload true), like documents_me_upload_start: this call with field_key and the file's name, size, content_type and sha256; PUT the bytes to the signed URL within 15 minutes with exactly the returned headers; then documents_me_field_file_finish. It replaces the file the field had. Accepted: the field's kinds up to its largest size. It counts toward your monthly self-upload limit (see documents_me_list self_upload), and your HR team is emailed when it arrives. Who sees it follows the field.","tags":["documents"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"field_key":{"type":"string","minLength":1,"maxLength":40,"description":"The file field's key (org_fields_list, type file)."},"file":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":500,"description":"The file name, e.g. \"Contract 2026.pdf\" (kept as metadata only)."},"size":{"type":"integer","exclusiveMinimum":true,"minimum":0,"description":"Bytes. Must equal what is uploaded."},"content_type":{"type":"string","minLength":1,"maxLength":200,"description":"application/pdf, image/png, image/jpeg, image/webp, image/heic, DOCX, XLSX, ODT or ODS MIME type, text/plain or text/csv. Must match the bytes."},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Lowercase hex SHA-256 of the file; checked against the upload."}},"required":["name","size","content_type","sha256"],"additionalProperties":false}},"required":["field_key","file"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"subject":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["person"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true}},"required":["kind","person"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["company"]}},"required":["kind"],"additionalProperties":false}]},"visibility":{"type":"string","enum":["hr","hr_person","hr_person_manager","everyone","managers","hr"]},"uploaded_by":{"type":"string","enum":["hr","self"],"description":"self: the person added it themself (\"From me\", or a custom field they fill in)."},"field":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"],"additionalProperties":false,"nullable":true,"description":"A custom file field's file (org_fields_list): its visibility follows the field's tier; replace or remove it through the field."},"expires_on":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true,"description":"null when you only see metadata."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The original file name; null when you only see metadata."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false},"access":{"type":"string","enum":["full","metadata"],"description":"metadata: title, category, date and size only (no notes, no download): API keys and AI assistants never get the contents of other people's documents."},"status":{"type":"string","enum":["pending","ready"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","category","subject","visibility","uploaded_by","field","expires_on","notes","file","access","status","created_at","updated_at"],"additionalProperties":false},"upload":{"type":"object","properties":{"url":{"type":"string","description":"Short-lived signed URL (15 minutes). Never share it."},"method":{"type":"string","enum":["PUT"]},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Send exactly these headers (they include the exact file size: any other size is refused)."},"resumable":{"type":"boolean","enum":[false],"description":"Always false: upload the whole file in one PUT."}},"required":["url","method","headers","resumable"],"additionalProperties":false,"nullable":true,"description":"null on a dry run."},"upload_expires_at":{"type":"string"}},"required":["document","upload","upload_expires_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/documents/me.field_file.finish":{"post":{"operationId":"documents.me.field_file.finish","summary":"Finish uploading my file for a field","description":"Finishes your field upload after the bytes were uploaded: Bizisy checks the file (size, SHA-256, type from the bytes) and your monthly limits, the field now holds it (the file it held before is deleted), and your HR team is emailed (never with the file name). Finishing twice returns the document.","tags":["documents"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"document_id":{"type":"string","minLength":1}},"required":["document_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"subject":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["person"]},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"nullable":true}},"required":["kind","person"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["company"]}},"required":["kind"],"additionalProperties":false}]},"visibility":{"type":"string","enum":["hr","hr_person","hr_person_manager","everyone","managers","hr"]},"uploaded_by":{"type":"string","enum":["hr","self"],"description":"self: the person added it themself (\"From me\", or a custom field they fill in)."},"field":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"],"additionalProperties":false,"nullable":true,"description":"A custom file field's file (org_fields_list): its visibility follows the field's tier; replace or remove it through the field."},"expires_on":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true,"description":"null when you only see metadata."},"file":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The original file name; null when you only see metadata."},"size":{"type":"integer"},"content_type":{"type":"string"},"previewable":{"type":"boolean","description":"The web app can show it (PDF, PNG, JPEG, WebP)."}},"required":["name","size","content_type","previewable"],"additionalProperties":false},"access":{"type":"string","enum":["full","metadata"],"description":"metadata: title, category, date and size only (no notes, no download): API keys and AI assistants never get the contents of other people's documents."},"status":{"type":"string","enum":["pending","ready"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","title","category","subject","visibility","uploaded_by","field","expires_on","notes","file","access","status","created_at","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/documents/me.field_file.remove":{"post":{"operationId":"documents.me.field_file.remove","summary":"Remove my file from a field","description":"Removes your file from one of your custom fields that your company lets people fill in (file.self_upload true): the file is deleted for good and the field is empty again. Fields HR fills in are changed by HR. Use dry_run first and confirm with the user.","tags":["documents"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"field_key":{"type":"string","minLength":1,"maxLength":40,"description":"The file field's key (org_fields_list, type file)."}},"required":["field_key"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"person_id":{"type":"string"},"field_key":{"type":"string"},"label":{"type":"string"},"removed":{"type":"boolean","enum":[true]}},"required":["person_id","field_key","label","removed"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/webhooks/events.list":{"post":{"operationId":"webhooks.events.list","summary":"List webhook event types","description":"Lists the event types an endpoint can subscribe to: type (e.g. person.hired), group and when it fires. Payloads carry ids, the time and the record's public and job details (never private or pay data); fetch more through the API. Owners and admins.","tags":["webhooks"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"group":{"type":"string"},"description":{"type":"string"}},"required":["type","group","description"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"webhooks.events.list","summary":"List webhook event types","description":"Lists the event types an endpoint can subscribe to: type (e.g. person.hired), group and when it fires. Payloads carry ids, the time and the record's public and job details (never private or pay data); fetch more through the API. Owners and admins.","tags":["webhooks"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"group":{"type":"string"},"description":{"type":"string"}},"required":["type","group","description"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/webhooks/endpoints.list":{"post":{"operationId":"webhooks.endpoints.list","summary":"List webhook endpoints","description":"Lists the organization's webhook endpoints, oldest first: URL, description, subscribed event types, whether it is on (disabled_reason says why not), health (failing_since, consecutive_failures, last_delivery) and the secret hint. Never returns secrets. Owners and admins.","tags":["webhooks"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"event_types":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"disabled_reason":{"type":"string","enum":["manual","failing","closed"],"nullable":true,"description":"Why it is off: manual (someone turned it off), failing (Bizisy turned it off after a day of failed deliveries), closed (company closure)."},"disabled_at":{"type":"string","nullable":true},"failing_since":{"type":"string","nullable":true,"description":"First failed attempt since the last success; null when the last attempt succeeded."},"consecutive_failures":{"type":"integer"},"last_delivery":{"type":"object","properties":{"at":{"type":"string"},"status":{"type":"string","enum":["succeeded","failed"]},"response_status":{"type":"integer","nullable":true}},"required":["at","status","response_status"],"additionalProperties":false,"nullable":true},"secret_hint":{"type":"string","description":"The signing secret's prefix and last 4 characters; the secret itself is shown only once."},"previous_secret_expires_at":{"type":"string","nullable":true,"description":"After a roll: until when the previous secret also signs each request."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","url","description","event_types","enabled","disabled_reason","disabled_at","failing_since","consecutive_failures","last_delivery","secret_hint","previous_secret_expires_at","created_at","updated_at"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"webhooks.endpoints.list","summary":"List webhook endpoints","description":"Lists the organization's webhook endpoints, oldest first: URL, description, subscribed event types, whether it is on (disabled_reason says why not), health (failing_since, consecutive_failures, last_delivery) and the secret hint. Never returns secrets. Owners and admins.","tags":["webhooks"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"event_types":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"disabled_reason":{"type":"string","enum":["manual","failing","closed"],"nullable":true,"description":"Why it is off: manual (someone turned it off), failing (Bizisy turned it off after a day of failed deliveries), closed (company closure)."},"disabled_at":{"type":"string","nullable":true},"failing_since":{"type":"string","nullable":true,"description":"First failed attempt since the last success; null when the last attempt succeeded."},"consecutive_failures":{"type":"integer"},"last_delivery":{"type":"object","properties":{"at":{"type":"string"},"status":{"type":"string","enum":["succeeded","failed"]},"response_status":{"type":"integer","nullable":true}},"required":["at","status","response_status"],"additionalProperties":false,"nullable":true},"secret_hint":{"type":"string","description":"The signing secret's prefix and last 4 characters; the secret itself is shown only once."},"previous_secret_expires_at":{"type":"string","nullable":true,"description":"After a roll: until when the previous secret also signs each request."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","url","description","event_types","enabled","disabled_reason","disabled_at","failing_since","consecutive_failures","last_delivery","secret_hint","previous_secret_expires_at","created_at","updated_at"],"additionalProperties":false}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/webhooks/endpoints.get":{"post":{"operationId":"webhooks.endpoints.get","summary":"Get a webhook endpoint","description":"Returns one webhook endpoint (as in webhooks_endpoints_list). Owners and admins.","tags":["webhooks"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"endpoint_id":{"type":"string","minLength":1}},"required":["endpoint_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"event_types":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"disabled_reason":{"type":"string","enum":["manual","failing","closed"],"nullable":true,"description":"Why it is off: manual (someone turned it off), failing (Bizisy turned it off after a day of failed deliveries), closed (company closure)."},"disabled_at":{"type":"string","nullable":true},"failing_since":{"type":"string","nullable":true,"description":"First failed attempt since the last success; null when the last attempt succeeded."},"consecutive_failures":{"type":"integer"},"last_delivery":{"type":"object","properties":{"at":{"type":"string"},"status":{"type":"string","enum":["succeeded","failed"]},"response_status":{"type":"integer","nullable":true}},"required":["at","status","response_status"],"additionalProperties":false,"nullable":true},"secret_hint":{"type":"string","description":"The signing secret's prefix and last 4 characters; the secret itself is shown only once."},"previous_secret_expires_at":{"type":"string","nullable":true,"description":"After a roll: until when the previous secret also signs each request."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","url","description","event_types","enabled","disabled_reason","disabled_at","failing_since","consecutive_failures","last_delivery","secret_hint","previous_secret_expires_at","created_at","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"webhooks.endpoints.get","summary":"Get a webhook endpoint","description":"Returns one webhook endpoint (as in webhooks_endpoints_list). Owners and admins.","tags":["webhooks"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"event_types":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"disabled_reason":{"type":"string","enum":["manual","failing","closed"],"nullable":true,"description":"Why it is off: manual (someone turned it off), failing (Bizisy turned it off after a day of failed deliveries), closed (company closure)."},"disabled_at":{"type":"string","nullable":true},"failing_since":{"type":"string","nullable":true,"description":"First failed attempt since the last success; null when the last attempt succeeded."},"consecutive_failures":{"type":"integer"},"last_delivery":{"type":"object","properties":{"at":{"type":"string"},"status":{"type":"string","enum":["succeeded","failed"]},"response_status":{"type":"integer","nullable":true}},"required":["at","status","response_status"],"additionalProperties":false,"nullable":true},"secret_hint":{"type":"string","description":"The signing secret's prefix and last 4 characters; the secret itself is shown only once."},"previous_secret_expires_at":{"type":"string","nullable":true,"description":"After a roll: until when the previous secret also signs each request."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","url","description","event_types","enabled","disabled_reason","disabled_at","failing_since","consecutive_failures","last_delivery","secret_hint","previous_secret_expires_at","created_at","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/webhooks/endpoints.create":{"post":{"operationId":"webhooks.endpoints.create","summary":"Add a webhook endpoint","description":"Registers an HTTPS endpoint that receives the chosen event types (event_types from webhooks_events_list; at least one) as signed POST requests (Standard Webhooks: webhook-id, webhook-timestamp, webhook-signature headers). url must be https:// with a public host name (no IP addresses, no private or Bizisy hosts, port 443 or 1024–65535); description is optional; enabled defaults to true. Returns the signing secret (whsec_…) ONCE: store it in the receiver to verify signatures. Only events that happen after it is added are sent. At most 10 endpoints. Owners and admins, in the app only (refused over an API key or MCP). A dry run checks the input and never issues a secret.","tags":["webhooks"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2000,"description":"https:// URL of your receiver (public host name, port 443 or 1024–65535)."},"description":{"type":"string","maxLength":200,"description":"What this endpoint is for, e.g. \"Payroll sync\".","default":""},"event_types":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":100,"description":"Event types to send, from webhooks_events_list."},"enabled":{"type":"boolean","default":true}},"required":["url","event_types"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"event_types":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"disabled_reason":{"type":"string","enum":["manual","failing","closed"],"nullable":true,"description":"Why it is off: manual (someone turned it off), failing (Bizisy turned it off after a day of failed deliveries), closed (company closure)."},"disabled_at":{"type":"string","nullable":true},"failing_since":{"type":"string","nullable":true,"description":"First failed attempt since the last success; null when the last attempt succeeded."},"consecutive_failures":{"type":"integer"},"last_delivery":{"type":"object","properties":{"at":{"type":"string"},"status":{"type":"string","enum":["succeeded","failed"]},"response_status":{"type":"integer","nullable":true}},"required":["at","status","response_status"],"additionalProperties":false,"nullable":true},"secret_hint":{"type":"string","description":"The signing secret's prefix and last 4 characters; the secret itself is shown only once."},"previous_secret_expires_at":{"type":"string","nullable":true,"description":"After a roll: until when the previous secret also signs each request."},"created_at":{"type":"string"},"updated_at":{"type":"string"},"secret":{"type":"string","description":"The signing secret. Shown once; roll it with webhooks_endpoints_roll_secret if lost."}},"required":["id","url","description","event_types","enabled","disabled_reason","disabled_at","failing_since","consecutive_failures","last_delivery","secret_hint","previous_secret_expires_at","created_at","updated_at","secret"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/webhooks/endpoints.update":{"post":{"operationId":"webhooks.endpoints.update","summary":"Change a webhook endpoint","description":"Changes an endpoint's url, description, event_types or enabled. Turning it off stops its pending deliveries (they become failed with endpoint_disabled; resend them later). Turning it back on clears the failure state, including after Bizisy turned it off for failing. A new host stops pending deliveries too, and every owner and admin is emailed. The secret is unchanged (see webhooks_endpoints_roll_secret). Over an API key or MCP only turning it off, the description and removing event types are allowed: a new URL, more events or turning it on happen in the app. Owners and admins.","tags":["webhooks"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"endpoint_id":{"type":"string","minLength":1},"url":{"type":"string","minLength":1,"maxLength":2000,"description":"https:// URL of your receiver (public host name, port 443 or 1024–65535)."},"description":{"type":"string","maxLength":200,"description":"What this endpoint is for, e.g. \"Payroll sync\"."},"event_types":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":100,"description":"Event types to send, from webhooks_events_list."},"enabled":{"type":"boolean"}},"required":["endpoint_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"event_types":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"disabled_reason":{"type":"string","enum":["manual","failing","closed"],"nullable":true,"description":"Why it is off: manual (someone turned it off), failing (Bizisy turned it off after a day of failed deliveries), closed (company closure)."},"disabled_at":{"type":"string","nullable":true},"failing_since":{"type":"string","nullable":true,"description":"First failed attempt since the last success; null when the last attempt succeeded."},"consecutive_failures":{"type":"integer"},"last_delivery":{"type":"object","properties":{"at":{"type":"string"},"status":{"type":"string","enum":["succeeded","failed"]},"response_status":{"type":"integer","nullable":true}},"required":["at","status","response_status"],"additionalProperties":false,"nullable":true},"secret_hint":{"type":"string","description":"The signing secret's prefix and last 4 characters; the secret itself is shown only once."},"previous_secret_expires_at":{"type":"string","nullable":true,"description":"After a roll: until when the previous secret also signs each request."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","url","description","event_types","enabled","disabled_reason","disabled_at","failing_since","consecutive_failures","last_delivery","secret_hint","previous_secret_expires_at","created_at","updated_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/webhooks/endpoints.delete":{"post":{"operationId":"webhooks.endpoints.delete","summary":"Delete a webhook endpoint","description":"Deletes an endpoint and its delivery log. Nothing more is sent to it. Cannot be undone. Owners and admins, in the app only.","tags":["webhooks"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"endpoint_id":{"type":"string","minLength":1}},"required":["endpoint_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/webhooks/endpoints.roll_secret":{"post":{"operationId":"webhooks.endpoints.roll_secret","summary":"Roll a webhook signing secret","description":"Replaces an endpoint's signing secret. Returns the new secret ONCE. For overlap_hours (0–72, default 24) every request carries signatures with both the new and the previous secret, so the receiver can switch without missing events; 0 stops the previous secret at once (use it when the secret leaked). Owners and admins, in the app only (the result is a secret).","tags":["webhooks"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"endpoint_id":{"type":"string","minLength":1},"overlap_hours":{"type":"integer","minimum":0,"maximum":72,"default":24}},"required":["endpoint_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"endpoint":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"event_types":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"disabled_reason":{"type":"string","enum":["manual","failing","closed"],"nullable":true,"description":"Why it is off: manual (someone turned it off), failing (Bizisy turned it off after a day of failed deliveries), closed (company closure)."},"disabled_at":{"type":"string","nullable":true},"failing_since":{"type":"string","nullable":true,"description":"First failed attempt since the last success; null when the last attempt succeeded."},"consecutive_failures":{"type":"integer"},"last_delivery":{"type":"object","properties":{"at":{"type":"string"},"status":{"type":"string","enum":["succeeded","failed"]},"response_status":{"type":"integer","nullable":true}},"required":["at","status","response_status"],"additionalProperties":false,"nullable":true},"secret_hint":{"type":"string","description":"The signing secret's prefix and last 4 characters; the secret itself is shown only once."},"previous_secret_expires_at":{"type":"string","nullable":true,"description":"After a roll: until when the previous secret also signs each request."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","url","description","event_types","enabled","disabled_reason","disabled_at","failing_since","consecutive_failures","last_delivery","secret_hint","previous_secret_expires_at","created_at","updated_at"],"additionalProperties":false},"secret":{"type":"string"}},"required":["endpoint","secret"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/webhooks/endpoints.test":{"post":{"operationId":"webhooks.endpoints.test","summary":"Send a test event","description":"Queues a webhook.test event for one endpoint; it is sent within about a minute, signed like every event, and appears in the delivery log (webhooks_deliveries_list). The endpoint must be on. At most 30 test events and resends per endpoint per hour. Owners and admins.","tags":["webhooks"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"endpoint_id":{"type":"string","minLength":1}},"required":["endpoint_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"endpoint_id":{"type":"string"},"event_type":{"type":"string"},"message_id":{"type":"string","description":"The webhook-id header: the same on every retry and resend."},"status":{"type":"string","enum":["pending","succeeded","failed"]},"attempts":{"type":"integer"},"max_attempts":{"type":"integer"},"next_attempt_at":{"type":"string","nullable":true},"last_attempt_at":{"type":"string","nullable":true},"response_status":{"type":"integer","nullable":true},"duration_ms":{"type":"integer","nullable":true},"error":{"type":"string","nullable":true,"description":"Why the last attempt failed: timeout, dns, blocked_address (the host resolves to a private address), connection, tls, redirect (redirects are never followed), http_status (not 2xx), invalid_url, endpoint_disabled, not_configured."},"test":{"type":"boolean"},"event_at":{"type":"string"},"created_at":{"type":"string"}},"required":["id","endpoint_id","event_type","message_id","status","attempts","max_attempts","next_attempt_at","last_attempt_at","response_status","duration_ms","error","test","event_at","created_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/webhooks/deliveries.list":{"post":{"operationId":"webhooks.deliveries.list","summary":"List webhook deliveries","description":"The delivery log of one endpoint (last 30 days), newest first: event type, status (pending, succeeded, failed), attempts, the last response status, duration and error. Filter by status; page with before = the previous page's next_before. limit 1–100 (default 25). Owners and admins.","tags":["webhooks"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"endpoint_id":{"type":"string","minLength":1},"status":{"type":"string","enum":["pending","succeeded","failed"]},"before":{"type":"string","minLength":1},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25}},"required":["endpoint_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"deliveries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"endpoint_id":{"type":"string"},"event_type":{"type":"string"},"message_id":{"type":"string","description":"The webhook-id header: the same on every retry and resend."},"status":{"type":"string","enum":["pending","succeeded","failed"]},"attempts":{"type":"integer"},"max_attempts":{"type":"integer"},"next_attempt_at":{"type":"string","nullable":true},"last_attempt_at":{"type":"string","nullable":true},"response_status":{"type":"integer","nullable":true},"duration_ms":{"type":"integer","nullable":true},"error":{"type":"string","nullable":true,"description":"Why the last attempt failed: timeout, dns, blocked_address (the host resolves to a private address), connection, tls, redirect (redirects are never followed), http_status (not 2xx), invalid_url, endpoint_disabled, not_configured."},"test":{"type":"boolean"},"event_at":{"type":"string"},"created_at":{"type":"string"}},"required":["id","endpoint_id","event_type","message_id","status","attempts","max_attempts","next_attempt_at","last_attempt_at","response_status","duration_ms","error","test","event_at","created_at"],"additionalProperties":false}},"next_before":{"type":"string","nullable":true}},"required":["deliveries","next_before"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"webhooks.deliveries.list","summary":"List webhook deliveries","description":"The delivery log of one endpoint (last 30 days), newest first: event type, status (pending, succeeded, failed), attempts, the last response status, duration and error. Filter by status; page with before = the previous page's next_before. limit 1–100 (default 25). Owners and admins.","tags":["webhooks"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"deliveries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"endpoint_id":{"type":"string"},"event_type":{"type":"string"},"message_id":{"type":"string","description":"The webhook-id header: the same on every retry and resend."},"status":{"type":"string","enum":["pending","succeeded","failed"]},"attempts":{"type":"integer"},"max_attempts":{"type":"integer"},"next_attempt_at":{"type":"string","nullable":true},"last_attempt_at":{"type":"string","nullable":true},"response_status":{"type":"integer","nullable":true},"duration_ms":{"type":"integer","nullable":true},"error":{"type":"string","nullable":true,"description":"Why the last attempt failed: timeout, dns, blocked_address (the host resolves to a private address), connection, tls, redirect (redirects are never followed), http_status (not 2xx), invalid_url, endpoint_disabled, not_configured."},"test":{"type":"boolean"},"event_at":{"type":"string"},"created_at":{"type":"string"}},"required":["id","endpoint_id","event_type","message_id","status","attempts","max_attempts","next_attempt_at","last_attempt_at","response_status","duration_ms","error","test","event_at","created_at"],"additionalProperties":false}},"next_before":{"type":"string","nullable":true}},"required":["deliveries","next_before"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/webhooks/deliveries.get":{"post":{"operationId":"webhooks.deliveries.get","summary":"Get a webhook delivery","description":"One delivery: the JSON body as it would be sent now (payload; delivery records keep ids only and each attempt fills in the record's current public and job details), its attempts and the start of the last answer (response_excerpt, at most 1 KB). Owners and admins.","tags":["webhooks"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"delivery_id":{"type":"string","minLength":1}},"required":["delivery_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"endpoint_id":{"type":"string"},"event_type":{"type":"string"},"message_id":{"type":"string","description":"The webhook-id header: the same on every retry and resend."},"status":{"type":"string","enum":["pending","succeeded","failed"]},"attempts":{"type":"integer"},"max_attempts":{"type":"integer"},"next_attempt_at":{"type":"string","nullable":true},"last_attempt_at":{"type":"string","nullable":true},"response_status":{"type":"integer","nullable":true},"duration_ms":{"type":"integer","nullable":true},"error":{"type":"string","nullable":true,"description":"Why the last attempt failed: timeout, dns, blocked_address (the host resolves to a private address), connection, tls, redirect (redirects are never followed), http_status (not 2xx), invalid_url, endpoint_disabled, not_configured."},"test":{"type":"boolean"},"event_at":{"type":"string"},"created_at":{"type":"string"},"payload":{"description":"The JSON body as it would be sent now: delivery records keep ids only, and the record's details are filled in at each attempt."},"attempt_log":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string"},"response_status":{"type":"integer","nullable":true},"duration_ms":{"type":"integer"},"error":{"type":"string","nullable":true}},"required":["at","response_status","duration_ms","error"],"additionalProperties":false}},"response_excerpt":{"type":"string","nullable":true,"description":"The start of the last answer (at most 1 KB)."}},"required":["id","endpoint_id","event_type","message_id","status","attempts","max_attempts","next_attempt_at","last_attempt_at","response_status","duration_ms","error","test","event_at","created_at","attempt_log","response_excerpt"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]},"get":{"operationId":"webhooks.deliveries.get","summary":"Get a webhook delivery","description":"One delivery: the JSON body as it would be sent now (payload; delivery records keep ids only and each attempt fills in the record's current public and job details), its attempts and the start of the last answer (response_excerpt, at most 1 KB). Owners and admins.","tags":["webhooks"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"endpoint_id":{"type":"string"},"event_type":{"type":"string"},"message_id":{"type":"string","description":"The webhook-id header: the same on every retry and resend."},"status":{"type":"string","enum":["pending","succeeded","failed"]},"attempts":{"type":"integer"},"max_attempts":{"type":"integer"},"next_attempt_at":{"type":"string","nullable":true},"last_attempt_at":{"type":"string","nullable":true},"response_status":{"type":"integer","nullable":true},"duration_ms":{"type":"integer","nullable":true},"error":{"type":"string","nullable":true,"description":"Why the last attempt failed: timeout, dns, blocked_address (the host resolves to a private address), connection, tls, redirect (redirects are never followed), http_status (not 2xx), invalid_url, endpoint_disabled, not_configured."},"test":{"type":"boolean"},"event_at":{"type":"string"},"created_at":{"type":"string"},"payload":{"description":"The JSON body as it would be sent now: delivery records keep ids only, and the record's details are filled in at each attempt."},"attempt_log":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string"},"response_status":{"type":"integer","nullable":true},"duration_ms":{"type":"integer"},"error":{"type":"string","nullable":true}},"required":["at","response_status","duration_ms","error"],"additionalProperties":false}},"response_excerpt":{"type":"string","nullable":true,"description":"The start of the last answer (at most 1 KB)."}},"required":["id","endpoint_id","event_type","message_id","status","attempts","max_attempts","next_attempt_at","last_attempt_at","response_status","duration_ms","error","test","event_at","created_at","attempt_log","response_excerpt"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}},"/v1/webhooks/deliveries.resend":{"post":{"operationId":"webhooks.deliveries.resend","summary":"Resend a webhook delivery","description":"Sends a delivery again with a fresh retry schedule (same webhook-id, so receivers that already processed it can skip it; the record's details are as they are when it is sent). Within about a minute. Not for pending deliveries; the endpoint must be on. At most 30 test events and resends per endpoint per hour. Owners and admins.","tags":["webhooks"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"Validate and preview without saving."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retried write safe: the first result for this key is stored for 24 hours and replayed (with Idempotent-Replayed: true) for an identical retry. Reusing the key for a different request is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"delivery_id":{"type":"string","minLength":1}},"required":["delivery_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"endpoint_id":{"type":"string"},"event_type":{"type":"string"},"message_id":{"type":"string","description":"The webhook-id header: the same on every retry and resend."},"status":{"type":"string","enum":["pending","succeeded","failed"]},"attempts":{"type":"integer"},"max_attempts":{"type":"integer"},"next_attempt_at":{"type":"string","nullable":true},"last_attempt_at":{"type":"string","nullable":true},"response_status":{"type":"integer","nullable":true},"duration_ms":{"type":"integer","nullable":true},"error":{"type":"string","nullable":true,"description":"Why the last attempt failed: timeout, dns, blocked_address (the host resolves to a private address), connection, tls, redirect (redirects are never followed), http_status (not 2xx), invalid_url, endpoint_disabled, not_configured."},"test":{"type":"boolean"},"event_at":{"type":"string"},"created_at":{"type":"string"}},"required":["id","endpoint_id","event_type","message_id","status","attempts","max_attempts","next_attempt_at","last_attempt_at","response_status","duration_ms","error","test","event_at","created_at"],"additionalProperties":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":[]}]}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key: hrk_<id>_<secret>"}},"responses":{"RateLimited":{"description":"Too many requests for this API key. Retry after the number of seconds in Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Error":{"description":"Error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"schemas":{"ErrorEnvelope":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}