{"openapi":"3.1.0","info":{"title":"Public API","version":"1.0.0","description":"Enterprise REST API for integrating external systems: manage members, customers, sites, and read shifts and bookings, plus outbound webhooks. Authenticate with a bearer API key created in the Developer portal."},"servers":[{"url":"https://keepworkersfirst.org/api/v1"}],"security":[{"apiKey":[]}],"tags":[{"name":"Organization"},{"name":"Members"},{"name":"Customers"},{"name":"Sites"},{"name":"Shifts"},{"name":"timesheets"},{"name":"invoices"},{"name":"Bookings"},{"name":"Webhooks"}],"paths":{"/v1/organization":{"get":{"operationId":"organization.get","summary":"Get your organization","description":"Returns the organization this API key belongs to. With a test-mode key this is the sandbox organization the request resolved to (`sandbox: true`).\n\n**Scope:** `organization:read`","tags":["Organization"],"security":[{"apiKey":["organization:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Organization id (the sandbox org id in test mode)."},"name":{"type":"string"},"slug":{"type":"string"},"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"website":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["draft","demo","active","suspended","cancelled"]},"sandbox":{"type":"boolean","description":"True when this request resolved to a sandbox (test-mode key)."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","name","slug","logo_url","website","status","sandbox","created_at"],"additionalProperties":false},"example":{"id":"3f8e4c1a-8b2d-4e6f-9a3b-5c7d9e1f2a4b","name":"Acme Staffing Group","slug":"acme-staffing-group","logo_url":null,"website":"https://example.com","status":"active","sandbox":false,"created_at":"2026-01-15T09:30:00+00:00"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/members":{"get":{"operationId":"members.list","summary":"List members","description":"Returns a paginated list of members (service providers) in your organization, newest first. Filter by status, verification, or active state.\n\n**Scope:** `members:read`\n**Requires module:** `members`","tags":["Members"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous response’s next_cursor.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by lifecycle status.","schema":{"type":"string","enum":["invited","active","inactive","draft"]}},{"name":"is_verified","in":"query","required":false,"description":"Filter by verification state.","schema":{"type":"string","enum":["true","false"]}},{"name":"is_active","in":"query","required":false,"description":"Filter by active state.","schema":{"type":"string","enum":["true","false"]}}],"security":[{"apiKey":["members:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Member id."},"business_name":{"type":"string","description":"Business or working name."},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Personal display name, when different from business_name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["invited","active","inactive","draft"],"description":"Lifecycle status. API-created members start as draft."},"is_active":{"type":"boolean"},"is_verified":{"type":"boolean","description":"Set via POST /members/{id}/verify after your external checks pass."},"capacity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many concurrent placements/clients this member can take."},"age_groups":{"type":"array","items":{"type":"string"},"description":"Industry-specific service groups."},"employment_relationship":{"type":"string","enum":["direct_employee","contractor","independent","agency_worker","volunteer","apprentice"]},"contract_type":{"anyOf":[{"type":"string","enum":["permanent","fixed_term","casual","seasonal","project_based"]},{"type":"null"}]},"contract_start_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"contract_end_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"contact":{"type":"object","properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["email","phone"],"additionalProperties":false,"description":"Contact details. Fields are null when not on file."},"address":{"type":"object","properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}]},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false,"description":"Postal address. Fields are null when not on file."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","business_name","display_name","description","status","is_active","is_verified","capacity","age_groups","employment_relationship","contract_type","contract_start_date","contract_end_date","contact","address","created_at","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean","description":"True when more results exist beyond this page."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass as ?cursor= to fetch the next page."}},"required":["data","has_more","next_cursor"],"additionalProperties":false},"example":{"data":[{"id":"a1b2c3d4-1111-4a2b-8c3d-e4f5a6b7c8d9","business_name":"Example Care Services","display_name":null,"description":"Experienced overnight-availability team member.","status":"active","is_active":true,"is_verified":true,"capacity":6,"age_groups":["infant","toddler"],"employment_relationship":"contractor","contract_type":"casual","contract_start_date":"2026-02-01","contract_end_date":null,"contact":{"email":"member@example.com","phone":null},"address":{"line1":null,"line2":null,"city":"Portland","state":"OR","postal_code":null,"country":"US"},"created_at":"2026-02-01T17:20:00+00:00","updated_at":"2026-06-28T09:12:00+00:00"}],"has_more":false,"next_cursor":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"members.create","summary":"Create a member","description":"Creates a new member in draft status. Use PATCH and the verify endpoint to complete onboarding. Emits member.created with source \"api\".\n\n**Scope:** `members:write`\n**Requires module:** `members`\n**Emits:** `member.created`","tags":["Members"],"security":[{"apiKey":["members:write"]}],"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Member id."},"business_name":{"type":"string","description":"Business or working name."},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Personal display name, when different from business_name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["invited","active","inactive","draft"],"description":"Lifecycle status. API-created members start as draft."},"is_active":{"type":"boolean"},"is_verified":{"type":"boolean","description":"Set via POST /members/{id}/verify after your external checks pass."},"capacity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many concurrent placements/clients this member can take."},"age_groups":{"type":"array","items":{"type":"string"},"description":"Industry-specific service groups."},"employment_relationship":{"type":"string","enum":["direct_employee","contractor","independent","agency_worker","volunteer","apprentice"]},"contract_type":{"anyOf":[{"type":"string","enum":["permanent","fixed_term","casual","seasonal","project_based"]},{"type":"null"}]},"contract_start_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"contract_end_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"contact":{"type":"object","properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["email","phone"],"additionalProperties":false,"description":"Contact details. Fields are null when not on file."},"address":{"type":"object","properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}]},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false,"description":"Postal address. Fields are null when not on file."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","business_name","display_name","description","status","is_active","is_verified","capacity","age_groups","employment_relationship","contract_type","contract_start_date","contract_end_date","contact","address","created_at","updated_at"],"additionalProperties":false},"example":{"id":"a1b2c3d4-1111-4a2b-8c3d-e4f5a6b7c8d9","business_name":"Example Care Services","display_name":null,"description":"Experienced overnight-availability team member.","status":"draft","is_active":true,"is_verified":false,"capacity":6,"age_groups":["infant","toddler"],"employment_relationship":"contractor","contract_type":"casual","contract_start_date":"2026-02-01","contract_end_date":null,"contact":{"email":"member@example.com","phone":null},"address":{"line1":null,"line2":null,"city":"Portland","state":"OR","postal_code":null,"country":"US"},"created_at":"2026-02-01T17:20:00+00:00","updated_at":"2026-06-28T09:12:00+00:00"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"business_name":{"type":"string","minLength":1,"description":"Business or working name (required)."},"display_name":{"description":"Personal display name.","type":"string"},"description":{"type":"string"},"capacity":{"type":"integer","minimum":0,"maximum":9007199254740991},"contact":{"type":"object","properties":{"email":{"type":"string"},"phone":{"type":"string"}}}},"required":["business_name"]},"example":{"business_name":"Example Care Services","capacity":6}}}}}},"/v1/members/{id}":{"get":{"operationId":"members.get","summary":"Get a member","description":"Returns a single member by id. Responds 404 if no such member exists in your organization.\n\n**Scope:** `members:read`\n**Requires module:** `members`","tags":["Members"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Member id."}}],"security":[{"apiKey":["members:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Member id."},"business_name":{"type":"string","description":"Business or working name."},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Personal display name, when different from business_name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["invited","active","inactive","draft"],"description":"Lifecycle status. API-created members start as draft."},"is_active":{"type":"boolean"},"is_verified":{"type":"boolean","description":"Set via POST /members/{id}/verify after your external checks pass."},"capacity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many concurrent placements/clients this member can take."},"age_groups":{"type":"array","items":{"type":"string"},"description":"Industry-specific service groups."},"employment_relationship":{"type":"string","enum":["direct_employee","contractor","independent","agency_worker","volunteer","apprentice"]},"contract_type":{"anyOf":[{"type":"string","enum":["permanent","fixed_term","casual","seasonal","project_based"]},{"type":"null"}]},"contract_start_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"contract_end_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"contact":{"type":"object","properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["email","phone"],"additionalProperties":false,"description":"Contact details. Fields are null when not on file."},"address":{"type":"object","properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}]},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false,"description":"Postal address. Fields are null when not on file."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","business_name","display_name","description","status","is_active","is_verified","capacity","age_groups","employment_relationship","contract_type","contract_start_date","contract_end_date","contact","address","created_at","updated_at"],"additionalProperties":false},"example":{"id":"a1b2c3d4-1111-4a2b-8c3d-e4f5a6b7c8d9","business_name":"Example Care Services","display_name":null,"description":"Experienced overnight-availability team member.","status":"active","is_active":true,"is_verified":true,"capacity":6,"age_groups":["infant","toddler"],"employment_relationship":"contractor","contract_type":"casual","contract_start_date":"2026-02-01","contract_end_date":null,"contact":{"email":"member@example.com","phone":null},"address":{"line1":null,"line2":null,"city":"Portland","state":"OR","postal_code":null,"country":"US"},"created_at":"2026-02-01T17:20:00+00:00","updated_at":"2026-06-28T09:12:00+00:00"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"members.update","summary":"Update a member","description":"Updates a member’s profile fields. Only supplied fields change. Emits member.updated.\n\n**Scope:** `members:write`\n**Requires module:** `members`\n**Emits:** `member.updated`","tags":["Members"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Member id."}}],"security":[{"apiKey":["members:write"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Member id."},"business_name":{"type":"string","description":"Business or working name."},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Personal display name, when different from business_name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["invited","active","inactive","draft"],"description":"Lifecycle status. API-created members start as draft."},"is_active":{"type":"boolean"},"is_verified":{"type":"boolean","description":"Set via POST /members/{id}/verify after your external checks pass."},"capacity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many concurrent placements/clients this member can take."},"age_groups":{"type":"array","items":{"type":"string"},"description":"Industry-specific service groups."},"employment_relationship":{"type":"string","enum":["direct_employee","contractor","independent","agency_worker","volunteer","apprentice"]},"contract_type":{"anyOf":[{"type":"string","enum":["permanent","fixed_term","casual","seasonal","project_based"]},{"type":"null"}]},"contract_start_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"contract_end_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"contact":{"type":"object","properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["email","phone"],"additionalProperties":false,"description":"Contact details. Fields are null when not on file."},"address":{"type":"object","properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}]},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false,"description":"Postal address. Fields are null when not on file."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","business_name","display_name","description","status","is_active","is_verified","capacity","age_groups","employment_relationship","contract_type","contract_start_date","contract_end_date","contact","address","created_at","updated_at"],"additionalProperties":false},"example":{"id":"a1b2c3d4-1111-4a2b-8c3d-e4f5a6b7c8d9","business_name":"Example Care Services","display_name":null,"description":"Experienced overnight-availability team member.","status":"active","is_active":true,"is_verified":true,"capacity":6,"age_groups":["infant","toddler"],"employment_relationship":"contractor","contract_type":"casual","contract_start_date":"2026-02-01","contract_end_date":null,"contact":{"email":"member@example.com","phone":null},"address":{"line1":null,"line2":null,"city":"Portland","state":"OR","postal_code":null,"country":"US"},"created_at":"2026-02-01T17:20:00+00:00","updated_at":"2026-06-28T09:12:00+00:00"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"business_name":{"type":"string","minLength":1},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"capacity":{"type":"integer","minimum":0,"maximum":9007199254740991},"contact":{"type":"object","properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}},"example":{"description":"Updated bio."}}}}}},"/v1/members/{id}/verify":{"post":{"operationId":"members.verify","summary":"Verify a member","description":"Marks a member as verified (is_verified = true) after your external checks pass. Emits member.verified.\n\n**Scope:** `members:write`\n**Requires module:** `members`\n**Emits:** `member.verified`","tags":["Members"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Member id."}}],"security":[{"apiKey":["members:write"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Member id."},"business_name":{"type":"string","description":"Business or working name."},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Personal display name, when different from business_name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["invited","active","inactive","draft"],"description":"Lifecycle status. API-created members start as draft."},"is_active":{"type":"boolean"},"is_verified":{"type":"boolean","description":"Set via POST /members/{id}/verify after your external checks pass."},"capacity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many concurrent placements/clients this member can take."},"age_groups":{"type":"array","items":{"type":"string"},"description":"Industry-specific service groups."},"employment_relationship":{"type":"string","enum":["direct_employee","contractor","independent","agency_worker","volunteer","apprentice"]},"contract_type":{"anyOf":[{"type":"string","enum":["permanent","fixed_term","casual","seasonal","project_based"]},{"type":"null"}]},"contract_start_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"contract_end_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"contact":{"type":"object","properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["email","phone"],"additionalProperties":false,"description":"Contact details. Fields are null when not on file."},"address":{"type":"object","properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}]},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false,"description":"Postal address. Fields are null when not on file."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","business_name","display_name","description","status","is_active","is_verified","capacity","age_groups","employment_relationship","contract_type","contract_start_date","contract_end_date","contact","address","created_at","updated_at"],"additionalProperties":false},"example":{"id":"a1b2c3d4-1111-4a2b-8c3d-e4f5a6b7c8d9","business_name":"Example Care Services","display_name":null,"description":"Experienced overnight-availability team member.","status":"active","is_active":true,"is_verified":true,"capacity":6,"age_groups":["infant","toddler"],"employment_relationship":"contractor","contract_type":"casual","contract_start_date":"2026-02-01","contract_end_date":null,"contact":{"email":"member@example.com","phone":null},"address":{"line1":null,"line2":null,"city":"Portland","state":"OR","postal_code":null,"country":"US"},"created_at":"2026-02-01T17:20:00+00:00","updated_at":"2026-06-28T09:12:00+00:00"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}}}},"/v1/members/{id}/deactivate":{"post":{"operationId":"members.deactivate","summary":"Deactivate a member","description":"Deactivates a member (is_active = false, status = inactive). Emits member.deactivated.\n\n**Scope:** `members:write`\n**Requires module:** `members`\n**Emits:** `member.deactivated`","tags":["Members"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Member id."}}],"security":[{"apiKey":["members:write"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Member id."},"business_name":{"type":"string","description":"Business or working name."},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Personal display name, when different from business_name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["invited","active","inactive","draft"],"description":"Lifecycle status. API-created members start as draft."},"is_active":{"type":"boolean"},"is_verified":{"type":"boolean","description":"Set via POST /members/{id}/verify after your external checks pass."},"capacity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many concurrent placements/clients this member can take."},"age_groups":{"type":"array","items":{"type":"string"},"description":"Industry-specific service groups."},"employment_relationship":{"type":"string","enum":["direct_employee","contractor","independent","agency_worker","volunteer","apprentice"]},"contract_type":{"anyOf":[{"type":"string","enum":["permanent","fixed_term","casual","seasonal","project_based"]},{"type":"null"}]},"contract_start_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"contract_end_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"contact":{"type":"object","properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["email","phone"],"additionalProperties":false,"description":"Contact details. Fields are null when not on file."},"address":{"type":"object","properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}]},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false,"description":"Postal address. Fields are null when not on file."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","business_name","display_name","description","status","is_active","is_verified","capacity","age_groups","employment_relationship","contract_type","contract_start_date","contract_end_date","contact","address","created_at","updated_at"],"additionalProperties":false},"example":{"id":"a1b2c3d4-1111-4a2b-8c3d-e4f5a6b7c8d9","business_name":"Example Care Services","display_name":null,"description":"Experienced overnight-availability team member.","status":"inactive","is_active":false,"is_verified":true,"capacity":6,"age_groups":["infant","toddler"],"employment_relationship":"contractor","contract_type":"casual","contract_start_date":"2026-02-01","contract_end_date":null,"contact":{"email":"member@example.com","phone":null},"address":{"line1":null,"line2":null,"city":"Portland","state":"OR","postal_code":null,"country":"US"},"created_at":"2026-02-01T17:20:00+00:00","updated_at":"2026-06-28T09:12:00+00:00"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}}}},"/v1/customers":{"get":{"operationId":"customers.list","summary":"List customers","description":"Returns a paginated list of customers (client companies) in your organization, newest first.\n\n**Scope:** `customers:read`\n**Requires module:** `customers`","tags":["Customers"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous response’s next_cursor.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by status.","schema":{"type":"string","enum":["active","inactive","prospect"]}}],"security":[{"apiKey":["customers:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Customer id."},"name":{"type":"string","description":"Customer (client company) name."},"status":{"type":"string","enum":["active","inactive","prospect"]},"contact_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_email":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"address":{"type":"object","properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}]},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false,"description":"Postal address. Fields are null when not on file."},"contract_start":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"contract_end":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"billing_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Default billing rate for this customer."},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","name","status","contact_name","contact_email","contact_phone","address","contract_start","contract_end","billing_rate","notes","created_at","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean","description":"True when more results exist beyond this page."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass as ?cursor= to fetch the next page."}},"required":["data","has_more","next_cursor"],"additionalProperties":false},"example":{"data":[{"id":"b2c3d4e5-2222-4b3c-9d4e-f5a6b7c8d9e0","name":"Example Facilities Group","status":"active","contact_name":null,"contact_email":"operations@example.com","contact_phone":null,"address":{"line1":null,"line2":null,"city":"Seattle","state":"WA","postal_code":null,"country":"US"},"contract_start":"2026-01-01","contract_end":null,"billing_rate":42.5,"notes":null,"created_at":"2026-01-05T14:00:00+00:00","updated_at":"2026-06-01T10:30:00+00:00"}],"has_more":false,"next_cursor":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"customers.create","summary":"Create a customer","description":"Creates a new customer (client company). Emits customer.created.\n\n**Scope:** `customers:write`\n**Requires module:** `customers`\n**Emits:** `customer.created`","tags":["Customers"],"security":[{"apiKey":["customers:write"]}],"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Customer id."},"name":{"type":"string","description":"Customer (client company) name."},"status":{"type":"string","enum":["active","inactive","prospect"]},"contact_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_email":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"address":{"type":"object","properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}]},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false,"description":"Postal address. Fields are null when not on file."},"contract_start":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"contract_end":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"billing_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Default billing rate for this customer."},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","name","status","contact_name","contact_email","contact_phone","address","contract_start","contract_end","billing_rate","notes","created_at","updated_at"],"additionalProperties":false},"example":{"id":"b2c3d4e5-2222-4b3c-9d4e-f5a6b7c8d9e0","name":"Example Facilities Group","status":"active","contact_name":null,"contact_email":"operations@example.com","contact_phone":null,"address":{"line1":null,"line2":null,"city":"Seattle","state":"WA","postal_code":null,"country":"US"},"contract_start":"2026-01-01","contract_end":null,"billing_rate":42.5,"notes":null,"created_at":"2026-01-05T14:00:00+00:00","updated_at":"2026-06-01T10:30:00+00:00"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Customer (client company) name (required)."},"status":{"type":"string","enum":["active","inactive","prospect"]},"contact_name":{"type":"string"},"contact_email":{"type":"string"},"contact_phone":{"type":"string"},"billing_rate":{"type":"number"},"notes":{"type":"string"}},"required":["name"]},"example":{"name":"Example Facilities Group","status":"active"}}}}}},"/v1/customers/{id}":{"get":{"operationId":"customers.get","summary":"Get a customer","description":"Returns a single customer by id. Responds 404 if no such customer exists in your organization.\n\n**Scope:** `customers:read`\n**Requires module:** `customers`","tags":["Customers"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Customer id."}}],"security":[{"apiKey":["customers:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Customer id."},"name":{"type":"string","description":"Customer (client company) name."},"status":{"type":"string","enum":["active","inactive","prospect"]},"contact_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_email":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"address":{"type":"object","properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}]},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false,"description":"Postal address. Fields are null when not on file."},"contract_start":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"contract_end":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"billing_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Default billing rate for this customer."},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","name","status","contact_name","contact_email","contact_phone","address","contract_start","contract_end","billing_rate","notes","created_at","updated_at"],"additionalProperties":false},"example":{"id":"b2c3d4e5-2222-4b3c-9d4e-f5a6b7c8d9e0","name":"Example Facilities Group","status":"active","contact_name":null,"contact_email":"operations@example.com","contact_phone":null,"address":{"line1":null,"line2":null,"city":"Seattle","state":"WA","postal_code":null,"country":"US"},"contract_start":"2026-01-01","contract_end":null,"billing_rate":42.5,"notes":null,"created_at":"2026-01-05T14:00:00+00:00","updated_at":"2026-06-01T10:30:00+00:00"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"customers.update","summary":"Update a customer","description":"Updates a customer’s fields. Only supplied fields change. Emits customer.updated.\n\n**Scope:** `customers:write`\n**Requires module:** `customers`\n**Emits:** `customer.updated`","tags":["Customers"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Customer id."}}],"security":[{"apiKey":["customers:write"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Customer id."},"name":{"type":"string","description":"Customer (client company) name."},"status":{"type":"string","enum":["active","inactive","prospect"]},"contact_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_email":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"address":{"type":"object","properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}]},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false,"description":"Postal address. Fields are null when not on file."},"contract_start":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"contract_end":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"billing_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Default billing rate for this customer."},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","name","status","contact_name","contact_email","contact_phone","address","contract_start","contract_end","billing_rate","notes","created_at","updated_at"],"additionalProperties":false},"example":{"id":"b2c3d4e5-2222-4b3c-9d4e-f5a6b7c8d9e0","name":"Example Facilities Group","status":"active","contact_name":null,"contact_email":"operations@example.com","contact_phone":null,"address":{"line1":null,"line2":null,"city":"Seattle","state":"WA","postal_code":null,"country":"US"},"contract_start":"2026-01-01","contract_end":null,"billing_rate":42.5,"notes":null,"created_at":"2026-01-05T14:00:00+00:00","updated_at":"2026-06-01T10:30:00+00:00"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","inactive","prospect"]},"contact_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_email":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"billing_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"example":{"status":"inactive"}}}}}},"/v1/sites":{"get":{"operationId":"sites.list","summary":"List sites","description":"Returns a paginated list of sites (customer locations) in your organization, newest first. Filter by customer or active state.\n\n**Scope:** `customers:read`\n**Requires module:** `customers`","tags":["Sites"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous response’s next_cursor.","schema":{"type":"string"}},{"name":"customer_id","in":"query","required":false,"description":"Filter to a single customer’s sites.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"is_active","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}}],"security":[{"apiKey":["customers:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Site id."},"customer_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Owning customer id."},"name":{"type":"string","description":"Site name (e.g. a branch, venue, or facility)."},"address":{"type":"object","properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}]},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false,"description":"Postal address. Fields are null when not on file."},"is_active":{"type":"boolean"},"contact_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"orientation_required":{"type":"boolean","description":"Whether members must complete a site orientation before working here."},"staff_requirements":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Free-text staffing requirements for this site."},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","customer_id","name","address","is_active","contact_name","contact_phone","orientation_required","staff_requirements","notes","created_at","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean","description":"True when more results exist beyond this page."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass as ?cursor= to fetch the next page."}},"required":["data","has_more","next_cursor"],"additionalProperties":false},"example":{"data":[{"id":"c3d4e5f6-3333-4c4d-8e5f-a6b7c8d9e0f1","customer_id":"b2c3d4e5-2222-4b3c-9d4e-f5a6b7c8d9e0","name":"Example Group — North Campus","address":{"line1":null,"line2":null,"city":"Seattle","state":"WA","postal_code":null,"country":"US"},"is_active":true,"contact_name":null,"contact_phone":null,"orientation_required":true,"staff_requirements":"Two members on-site minimum during operating hours.","notes":null,"created_at":"2026-01-10T09:00:00+00:00","updated_at":"2026-05-20T16:45:00+00:00"}],"has_more":false,"next_cursor":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"sites.create","summary":"Create a site","description":"Creates a site under a customer you own. Emits customer_location.created.\n\n**Scope:** `customers:write`\n**Requires module:** `customers`\n**Emits:** `customer_location.created`","tags":["Sites"],"security":[{"apiKey":["customers:write"]}],"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Site id."},"customer_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Owning customer id."},"name":{"type":"string","description":"Site name (e.g. a branch, venue, or facility)."},"address":{"type":"object","properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}]},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false,"description":"Postal address. Fields are null when not on file."},"is_active":{"type":"boolean"},"contact_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"orientation_required":{"type":"boolean","description":"Whether members must complete a site orientation before working here."},"staff_requirements":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Free-text staffing requirements for this site."},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","customer_id","name","address","is_active","contact_name","contact_phone","orientation_required","staff_requirements","notes","created_at","updated_at"],"additionalProperties":false},"example":{"id":"c3d4e5f6-3333-4c4d-8e5f-a6b7c8d9e0f1","customer_id":"b2c3d4e5-2222-4b3c-9d4e-f5a6b7c8d9e0","name":"Example Group — North Campus","address":{"line1":null,"line2":null,"city":"Seattle","state":"WA","postal_code":null,"country":"US"},"is_active":true,"contact_name":null,"contact_phone":null,"orientation_required":true,"staff_requirements":"Two members on-site minimum during operating hours.","notes":null,"created_at":"2026-01-10T09:00:00+00:00","updated_at":"2026-05-20T16:45:00+00:00"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Owning customer id (required)."},"name":{"type":"string","minLength":1,"description":"Site name (required)."},"contact_name":{"type":"string"},"contact_phone":{"type":"string"},"orientation_required":{"type":"boolean"},"staff_requirements":{"type":"string"},"notes":{"type":"string"}},"required":["customer_id","name"]},"example":{"customer_id":"b2c3d4e5-2222-4b3c-9d4e-f5a6b7c8d9e0","name":"Example Group — North Campus"}}}}}},"/v1/sites/{id}":{"get":{"operationId":"sites.get","summary":"Get a site","description":"Returns a single site by id. Responds 404 if no such site exists in your organization.\n\n**Scope:** `customers:read`\n**Requires module:** `customers`","tags":["Sites"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Site id."}}],"security":[{"apiKey":["customers:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Site id."},"customer_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Owning customer id."},"name":{"type":"string","description":"Site name (e.g. a branch, venue, or facility)."},"address":{"type":"object","properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}]},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false,"description":"Postal address. Fields are null when not on file."},"is_active":{"type":"boolean"},"contact_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"orientation_required":{"type":"boolean","description":"Whether members must complete a site orientation before working here."},"staff_requirements":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Free-text staffing requirements for this site."},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","customer_id","name","address","is_active","contact_name","contact_phone","orientation_required","staff_requirements","notes","created_at","updated_at"],"additionalProperties":false},"example":{"id":"c3d4e5f6-3333-4c4d-8e5f-a6b7c8d9e0f1","customer_id":"b2c3d4e5-2222-4b3c-9d4e-f5a6b7c8d9e0","name":"Example Group — North Campus","address":{"line1":null,"line2":null,"city":"Seattle","state":"WA","postal_code":null,"country":"US"},"is_active":true,"contact_name":null,"contact_phone":null,"orientation_required":true,"staff_requirements":"Two members on-site minimum during operating hours.","notes":null,"created_at":"2026-01-10T09:00:00+00:00","updated_at":"2026-05-20T16:45:00+00:00"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"sites.update","summary":"Update a site","description":"Updates a site’s fields. Only supplied fields change. Emits customer_location.updated.\n\n**Scope:** `customers:write`\n**Requires module:** `customers`\n**Emits:** `customer_location.updated`","tags":["Sites"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Site id."}}],"security":[{"apiKey":["customers:write"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Site id."},"customer_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Owning customer id."},"name":{"type":"string","description":"Site name (e.g. a branch, venue, or facility)."},"address":{"type":"object","properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}]},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["line1","line2","city","state","postal_code","country"],"additionalProperties":false,"description":"Postal address. Fields are null when not on file."},"is_active":{"type":"boolean"},"contact_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"orientation_required":{"type":"boolean","description":"Whether members must complete a site orientation before working here."},"staff_requirements":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Free-text staffing requirements for this site."},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","customer_id","name","address","is_active","contact_name","contact_phone","orientation_required","staff_requirements","notes","created_at","updated_at"],"additionalProperties":false},"example":{"id":"c3d4e5f6-3333-4c4d-8e5f-a6b7c8d9e0f1","customer_id":"b2c3d4e5-2222-4b3c-9d4e-f5a6b7c8d9e0","name":"Example Group — North Campus","address":{"line1":null,"line2":null,"city":"Seattle","state":"WA","postal_code":null,"country":"US"},"is_active":true,"contact_name":null,"contact_phone":null,"orientation_required":true,"staff_requirements":"Two members on-site minimum during operating hours.","notes":null,"created_at":"2026-01-10T09:00:00+00:00","updated_at":"2026-05-20T16:45:00+00:00"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"is_active":{"type":"boolean"},"contact_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"orientation_required":{"type":"boolean"},"staff_requirements":{"anyOf":[{"type":"string"},{"type":"null"}]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"example":{"is_active":false}}}}}},"/v1/shifts":{"get":{"operationId":"shifts.list","summary":"List shifts","description":"Returns a paginated list of shifts in your organization, newest first. Filter by status, customer, site, or date range.\n\n**Scope:** `shifts:read`\n**Requires module:** `shift_placement`","tags":["Shifts"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous response’s next_cursor.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","open","filled","in_progress","completed","cancelled"]}},{"name":"customer_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"site_id","in":"query","required":false,"description":"Filter by site (customer location).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"date_from","in":"query","required":false,"description":"Only shifts on or after this date (YYYY-MM-DD).","schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"date_to","in":"query","required":false,"description":"Only shifts on or before this date (YYYY-MM-DD).","schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}}],"security":[{"apiKey":["shifts:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Shift id."},"status":{"type":"string","enum":["draft","open","filled","in_progress","completed","cancelled"]},"shift_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},"start_time":{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?$","description":"Time of day (HH:MM or HH:MM:SS)."},"end_time":{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?$","description":"Time of day (HH:MM or HH:MM:SS)."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display name / description of the shift."},"customer_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"Customer this shift is worked for, when applicable."},"site_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"Site (customer location) where the shift takes place."},"positions_needed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"positions_filled":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pay_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"pay_type":{"type":"string","enum":["hourly","flat","custom"]},"offer_type":{"type":"string","enum":["none","targeted","open_call"],"description":"How the shift was dispatched to members."},"confirmation_required":{"type":"boolean"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","status","shift_date","start_time","end_time","description","customer_id","site_id","positions_needed","positions_filled","pay_rate","pay_type","offer_type","confirmation_required","created_at","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean","description":"True when more results exist beyond this page."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass as ?cursor= to fetch the next page."}},"required":["data","has_more","next_cursor"],"additionalProperties":false},"example":{"data":[{"id":"d4e5f6a7-4444-4d5e-9f6a-b7c8d9e0f1a2","status":"open","shift_date":"2026-07-14","start_time":"09:00:00","end_time":"17:00:00","description":"Day coverage — North Campus front desk","customer_id":"b2c3d4e5-2222-4b3c-9d4e-f5a6b7c8d9e0","site_id":"c3d4e5f6-3333-4c4d-8e5f-a6b7c8d9e0f1","positions_needed":2,"positions_filled":1,"pay_rate":24,"pay_type":"hourly","offer_type":"open_call","confirmation_required":true,"created_at":"2026-07-01T12:00:00+00:00","updated_at":"2026-07-03T08:15:00+00:00"}],"has_more":false,"next_cursor":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/shifts/{id}":{"get":{"operationId":"shifts.get","summary":"Get a shift","description":"Returns a single shift by id with its assignments embedded. Responds 404 if no such shift exists in your organization.\n\n**Scope:** `shifts:read`\n**Requires module:** `shift_placement`","tags":["Shifts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Shift id."}}],"security":[{"apiKey":["shifts:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Shift id."},"status":{"type":"string","enum":["draft","open","filled","in_progress","completed","cancelled"]},"shift_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},"start_time":{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?$","description":"Time of day (HH:MM or HH:MM:SS)."},"end_time":{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?$","description":"Time of day (HH:MM or HH:MM:SS)."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display name / description of the shift."},"customer_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"Customer this shift is worked for, when applicable."},"site_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"Site (customer location) where the shift takes place."},"positions_needed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"positions_filled":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pay_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"pay_type":{"type":"string","enum":["hourly","flat","custom"]},"offer_type":{"type":"string","enum":["none","targeted","open_call"],"description":"How the shift was dispatched to members."},"confirmation_required":{"type":"boolean"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"assignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Assignment id."},"shift_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"member_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The assigned member."},"status":{"type":"string","enum":["offered","accepted","declined","completed","no_show","cancelled"]},"clock_in":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"clock_out":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"responded_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"confirmed_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"is_open_call":{"type":"boolean","description":"True when the member claimed an open call rather than a targeted offer."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","shift_id","member_id","status","clock_in","clock_out","responded_at","confirmed_at","is_open_call","created_at","updated_at"],"additionalProperties":false},"description":"Assignments on this shift."}},"required":["id","status","shift_date","start_time","end_time","description","customer_id","site_id","positions_needed","positions_filled","pay_rate","pay_type","offer_type","confirmation_required","created_at","updated_at","assignments"],"additionalProperties":false},"example":{"id":"d4e5f6a7-4444-4d5e-9f6a-b7c8d9e0f1a2","status":"open","shift_date":"2026-07-14","start_time":"09:00:00","end_time":"17:00:00","description":"Day coverage — North Campus front desk","customer_id":"b2c3d4e5-2222-4b3c-9d4e-f5a6b7c8d9e0","site_id":"c3d4e5f6-3333-4c4d-8e5f-a6b7c8d9e0f1","positions_needed":2,"positions_filled":1,"pay_rate":24,"pay_type":"hourly","offer_type":"open_call","confirmation_required":true,"created_at":"2026-07-01T12:00:00+00:00","updated_at":"2026-07-03T08:15:00+00:00","assignments":[{"id":"e5f6a7b8-5555-4e6f-8a7b-c8d9e0f1a2b3","shift_id":"d4e5f6a7-4444-4d5e-9f6a-b7c8d9e0f1a2","member_id":"a1b2c3d4-1111-4a2b-8c3d-e4f5a6b7c8d9","status":"accepted","clock_in":null,"clock_out":null,"responded_at":"2026-07-02T15:30:00+00:00","confirmed_at":"2026-07-02T15:30:00+00:00","is_open_call":true,"created_at":"2026-07-01T12:05:00+00:00","updated_at":"2026-07-02T15:30:00+00:00"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/shifts/{id}/assignments":{"get":{"operationId":"shifts.listAssignments","summary":"List a shift’s assignments","description":"Returns the assignments for a shift. Responds 404 if no such shift exists in your organization.\n\n**Scope:** `shifts:read`\n**Requires module:** `shift_placement`","tags":["Shifts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Shift id."}}],"security":[{"apiKey":["shifts:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Assignment id."},"shift_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"member_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The assigned member."},"status":{"type":"string","enum":["offered","accepted","declined","completed","no_show","cancelled"]},"clock_in":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"clock_out":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"responded_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"confirmed_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"is_open_call":{"type":"boolean","description":"True when the member claimed an open call rather than a targeted offer."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","shift_id","member_id","status","clock_in","clock_out","responded_at","confirmed_at","is_open_call","created_at","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean","description":"True when more results exist beyond this page."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass as ?cursor= to fetch the next page."}},"required":["data","has_more","next_cursor"],"additionalProperties":false},"example":{"data":[{"id":"e5f6a7b8-5555-4e6f-8a7b-c8d9e0f1a2b3","shift_id":"d4e5f6a7-4444-4d5e-9f6a-b7c8d9e0f1a2","member_id":"a1b2c3d4-1111-4a2b-8c3d-e4f5a6b7c8d9","status":"accepted","clock_in":null,"clock_out":null,"responded_at":"2026-07-02T15:30:00+00:00","confirmed_at":"2026-07-02T15:30:00+00:00","is_open_call":true,"created_at":"2026-07-01T12:05:00+00:00","updated_at":"2026-07-02T15:30:00+00:00"}],"has_more":false,"next_cursor":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/timesheets":{"get":{"operationId":"timesheets.list","summary":"List timesheets","description":"Returns a paginated list of timesheets in your organization, newest first. A timesheet records the worked, billable, and payable time for one shift assignment along with its approval state.\n\n**Scope:** `timesheets:read`\n**Requires module:** `shift_placement`","tags":["timesheets"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous response’s next_cursor.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","pending_approval","approved","disputed","voided"]}},{"name":"shift_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"member_id","in":"query","required":false,"description":"Filter by the member the timesheet belongs to.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"customer_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"date_from","in":"query","required":false,"description":"Only timesheets created on or after this date (YYYY-MM-DD).","schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"date_to","in":"query","required":false,"description":"Only timesheets created on or before this date (YYYY-MM-DD).","schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}}],"security":[{"apiKey":["timesheets:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Timesheet id."},"shift_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"assignment_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"member_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The member whose time this timesheet records."},"customer_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"Customer the shift was worked for, when applicable."},"status":{"type":"string","enum":["draft","pending_approval","approved","disputed","voided"]},"scheduled_start":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"scheduled_end":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"clock_in_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"clock_out_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"effective_start":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}],"description":"The billable window start after any admin correction."},"effective_end":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"scheduled_minutes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"worked_minutes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"billable_minutes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minutes billed to the customer after late policy + rounding."},"payable_minutes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minutes paid to the member after pay policy + rounding."},"late_minutes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"is_late":{"type":"boolean","description":"Checked in later than the grace period allows."},"missing_clock_out":{"type":"boolean"},"generated_by":{"type":"string","enum":["clock_out","cron_sweep","admin"]},"auto_approve_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}],"description":"When the pending approval auto-approves if unreviewed."},"approved_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"approval_method":{"anyOf":[{"type":"string","enum":["customer","auto_opt_out","auto_window","admin","auto_no_customer"]},{"type":"null"}]},"customer_note":{"anyOf":[{"type":"string"},{"type":"null"}]},"dispute_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","shift_id","assignment_id","member_id","customer_id","status","scheduled_start","scheduled_end","clock_in_at","clock_out_at","effective_start","effective_end","scheduled_minutes","worked_minutes","billable_minutes","payable_minutes","late_minutes","is_late","missing_clock_out","generated_by","auto_approve_at","approved_at","approval_method","customer_note","dispute_reason","created_at","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean","description":"True when more results exist beyond this page."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass as ?cursor= to fetch the next page."}},"required":["data","has_more","next_cursor"],"additionalProperties":false},"example":{"data":[{"id":"c1a97d9e-4b1f-4f7e-9f57-2f9f4b6f1a01","shift_id":"a3f6d0aa-9d3c-49e0-90ef-6d3c1b7a2b10","assignment_id":"b5e8c2bb-1c4d-4a1f-8a2e-7e4d2c8b3c21","member_id":"d7f0e4cc-3e6f-4c30-b4a0-9f6e3d0c4d32","customer_id":"e9a2f6dd-508a-4e52-a6b2-1a8f5e2d6e43","status":"approved","scheduled_start":"2026-07-08T14:00:00Z","scheduled_end":"2026-07-08T22:00:00Z","clock_in_at":"2026-07-08T14:04:12Z","clock_out_at":"2026-07-08T22:01:40Z","effective_start":"2026-07-08T14:04:12Z","effective_end":"2026-07-08T22:01:40Z","scheduled_minutes":480,"worked_minutes":477,"billable_minutes":480,"payable_minutes":480,"late_minutes":4,"is_late":false,"missing_clock_out":false,"generated_by":"clock_out","auto_approve_at":"2026-07-11T22:02:00Z","approved_at":"2026-07-09T09:15:00Z","approval_method":"customer","customer_note":null,"dispute_reason":null,"created_at":"2026-07-08T22:02:00Z","updated_at":"2026-07-09T09:15:00Z"}],"has_more":false,"next_cursor":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/timesheets/{id}":{"get":{"operationId":"timesheets.get","summary":"Get a timesheet","description":"Returns a single timesheet by id, including scheduled vs worked windows, policy-applied billable/payable minutes, and its approval state. Responds 404 if no such timesheet exists in your organization.\n\n**Scope:** `timesheets:read`\n**Requires module:** `shift_placement`","tags":["timesheets"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Timesheet id."}}],"security":[{"apiKey":["timesheets:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Timesheet id."},"shift_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"assignment_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"member_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The member whose time this timesheet records."},"customer_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"Customer the shift was worked for, when applicable."},"status":{"type":"string","enum":["draft","pending_approval","approved","disputed","voided"]},"scheduled_start":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"scheduled_end":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"clock_in_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"clock_out_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"effective_start":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}],"description":"The billable window start after any admin correction."},"effective_end":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"scheduled_minutes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"worked_minutes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"billable_minutes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minutes billed to the customer after late policy + rounding."},"payable_minutes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minutes paid to the member after pay policy + rounding."},"late_minutes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"is_late":{"type":"boolean","description":"Checked in later than the grace period allows."},"missing_clock_out":{"type":"boolean"},"generated_by":{"type":"string","enum":["clock_out","cron_sweep","admin"]},"auto_approve_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}],"description":"When the pending approval auto-approves if unreviewed."},"approved_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"approval_method":{"anyOf":[{"type":"string","enum":["customer","auto_opt_out","auto_window","admin","auto_no_customer"]},{"type":"null"}]},"customer_note":{"anyOf":[{"type":"string"},{"type":"null"}]},"dispute_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","shift_id","assignment_id","member_id","customer_id","status","scheduled_start","scheduled_end","clock_in_at","clock_out_at","effective_start","effective_end","scheduled_minutes","worked_minutes","billable_minutes","payable_minutes","late_minutes","is_late","missing_clock_out","generated_by","auto_approve_at","approved_at","approval_method","customer_note","dispute_reason","created_at","updated_at"],"additionalProperties":false},"example":{"id":"c1a97d9e-4b1f-4f7e-9f57-2f9f4b6f1a01","shift_id":"a3f6d0aa-9d3c-49e0-90ef-6d3c1b7a2b10","assignment_id":"b5e8c2bb-1c4d-4a1f-8a2e-7e4d2c8b3c21","member_id":"d7f0e4cc-3e6f-4c30-b4a0-9f6e3d0c4d32","customer_id":"e9a2f6dd-508a-4e52-a6b2-1a8f5e2d6e43","status":"approved","scheduled_start":"2026-07-08T14:00:00Z","scheduled_end":"2026-07-08T22:00:00Z","clock_in_at":"2026-07-08T14:04:12Z","clock_out_at":"2026-07-08T22:01:40Z","effective_start":"2026-07-08T14:04:12Z","effective_end":"2026-07-08T22:01:40Z","scheduled_minutes":480,"worked_minutes":477,"billable_minutes":480,"payable_minutes":480,"late_minutes":4,"is_late":false,"missing_clock_out":false,"generated_by":"clock_out","auto_approve_at":"2026-07-11T22:02:00Z","approved_at":"2026-07-09T09:15:00Z","approval_method":"customer","customer_note":null,"dispute_reason":null,"created_at":"2026-07-08T22:02:00Z","updated_at":"2026-07-09T09:15:00Z"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/invoices":{"get":{"operationId":"invoices.list","summary":"List invoices","description":"Returns a paginated list of invoices in your organization, newest first. Invoices are generated automatically from approved timesheets; filter by status, direction, member, or customer.\n\n**Scope:** `invoices:read`\n**Requires module:** `accounting`","tags":["invoices"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous response’s next_cursor.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","sent","paid","void"]}},{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["provider_to_org","org_to_customer","provider_to_customer"]}},{"name":"member_id","in":"query","required":false,"description":"Filter by billing member.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"customer_id","in":"query","required":false,"description":"Filter by billed customer.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"security":[{"apiKey":["invoices:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Invoice id."},"invoice_number":{"type":"string","description":"Per-organization sequential number, e.g. INV-000123."},"direction":{"type":"string","enum":["provider_to_org","org_to_customer","provider_to_customer"],"description":"Who bills whom: member→organization, organization→customer, or member→customer (direct flow)."},"member_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"Billing member for provider_* directions."},"customer_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"Billed customer for *_customer directions."},"status":{"type":"string","enum":["draft","sent","paid","void"]},"issue_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"due_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"period_start":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}],"description":"Consolidated-run period start, when batched."},"period_end":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"subtotal":{"type":"number"},"tax_total":{"type":"number"},"total":{"type":"number"},"amount_paid":{"type":"number"},"sent_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"paid_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"payment_reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"voided_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"void_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","invoice_number","direction","member_id","customer_id","status","issue_date","due_date","period_start","period_end","subtotal","tax_total","total","amount_paid","sent_at","paid_at","payment_reference","voided_at","void_reason","notes","created_at","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean","description":"True when more results exist beyond this page."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass as ?cursor= to fetch the next page."}},"required":["data","has_more","next_cursor"],"additionalProperties":false},"example":{"data":[{"id":"f2b3c4d5-6e7f-4a8b-9c0d-1e2f3a4b5c6d","invoice_number":"INV-000042","direction":"org_to_customer","member_id":null,"customer_id":"e9a2f6dd-508a-4e52-a6b2-1a8f5e2d6e43","status":"sent","issue_date":"2026-07-09","due_date":"2026-07-23","period_start":null,"period_end":null,"subtotal":384,"tax_total":33.6,"total":417.6,"amount_paid":0,"sent_at":"2026-07-09T10:05:00Z","paid_at":null,"payment_reference":null,"voided_at":null,"void_reason":null,"notes":null,"created_at":"2026-07-09T10:00:00Z","updated_at":"2026-07-09T10:05:00Z"}],"has_more":false,"next_cursor":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/invoices/{id}":{"get":{"operationId":"invoices.get","summary":"Get an invoice","description":"Returns a single invoice by id with its line items embedded. Responds 404 if no such invoice exists in your organization.\n\n**Scope:** `invoices:read`\n**Requires module:** `accounting`","tags":["invoices"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Invoice id."}}],"security":[{"apiKey":["invoices:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Invoice id."},"invoice_number":{"type":"string","description":"Per-organization sequential number, e.g. INV-000123."},"direction":{"type":"string","enum":["provider_to_org","org_to_customer","provider_to_customer"],"description":"Who bills whom: member→organization, organization→customer, or member→customer (direct flow)."},"member_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"Billing member for provider_* directions."},"customer_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"Billed customer for *_customer directions."},"status":{"type":"string","enum":["draft","sent","paid","void"]},"issue_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"due_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"period_start":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}],"description":"Consolidated-run period start, when batched."},"period_end":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"subtotal":{"type":"number"},"tax_total":{"type":"number"},"total":{"type":"number"},"amount_paid":{"type":"number"},"sent_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"paid_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"payment_reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"voided_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"void_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"invoice_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"line_index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"line_type":{"type":"string","enum":["timesheet","travel","tax","withholding","adjustment","custom"]},"description":{"type":"string"},"quantity":{"type":"number"},"unit":{"anyOf":[{"type":"string","enum":["hours","miles","flat","percent"]},{"type":"null"}]},"rate":{"type":"number"},"amount":{"type":"number","description":"Signed — withholding/adjustment lines may be negative."},"shift_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"member_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"customer_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","invoice_id","line_index","line_type","description","quantity","unit","rate","amount","shift_id","member_id","customer_id","created_at"],"additionalProperties":false},"description":"Line items on this invoice, in display order."}},"required":["id","invoice_number","direction","member_id","customer_id","status","issue_date","due_date","period_start","period_end","subtotal","tax_total","total","amount_paid","sent_at","paid_at","payment_reference","voided_at","void_reason","notes","created_at","updated_at","lines"],"additionalProperties":false},"example":{"id":"f2b3c4d5-6e7f-4a8b-9c0d-1e2f3a4b5c6d","invoice_number":"INV-000042","direction":"org_to_customer","member_id":null,"customer_id":"e9a2f6dd-508a-4e52-a6b2-1a8f5e2d6e43","status":"sent","issue_date":"2026-07-09","due_date":"2026-07-23","period_start":null,"period_end":null,"subtotal":384,"tax_total":33.6,"total":417.6,"amount_paid":0,"sent_at":"2026-07-09T10:05:00Z","paid_at":null,"payment_reference":null,"voided_at":null,"void_reason":null,"notes":null,"created_at":"2026-07-09T10:00:00Z","updated_at":"2026-07-09T10:05:00Z","lines":[{"id":"a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","invoice_id":"f2b3c4d5-6e7f-4a8b-9c0d-1e2f3a4b5c6d","line_index":0,"line_type":"timesheet","description":"2026-07-08 — Main St site — 8h @ $48.00","quantity":8,"unit":"hours","rate":48,"amount":384,"shift_id":"a3f6d0aa-9d3c-49e0-90ef-6d3c1b7a2b10","member_id":"d7f0e4cc-3e6f-4c30-b4a0-9f6e3d0c4d32","customer_id":"e9a2f6dd-508a-4e52-a6b2-1a8f5e2d6e43","created_at":"2026-07-09T10:00:00Z"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/bookings":{"get":{"operationId":"bookings.list","summary":"List bookings","description":"Returns a paginated list of bookings (enrollments) in your organization, newest first. Filter by status or booking type.\n\n**Scope:** `bookings:read`\n**Requires module:** `bookings`","tags":["Bookings"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous response’s next_cursor.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","approved","active","completed","cancelled"]}},{"name":"booking_type","in":"query","required":false,"schema":{"type":"string","enum":["one_time","recurring"]}}],"security":[{"apiKey":["bookings:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Booking id."},"status":{"type":"string","enum":["pending","approved","active","completed","cancelled"]},"booking_type":{"type":"string","enum":["one_time","recurring"]},"member_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The member (service provider) booked."},"child":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","first_name","last_name"],"additionalProperties":false},{"type":"null"}],"description":"The dependent this booking is for, when applicable."},"start_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"end_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"booking_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}],"description":"Date of a one-time booking."},"booking_start_time":{"anyOf":[{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?$","description":"Time of day (HH:MM or HH:MM:SS)."},{"type":"null"}]},"booking_end_time":{"anyOf":[{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?$","description":"Time of day (HH:MM or HH:MM:SS)."},{"type":"null"}]},"payment_amount":{"anyOf":[{"type":"number"},{"type":"null"}]},"payment_status":{"type":"string","enum":["pending","paid","refunded","failed","not_required"]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","status","booking_type","member_id","child","start_date","end_date","booking_date","booking_start_time","booking_end_time","payment_amount","payment_status","created_at","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean","description":"True when more results exist beyond this page."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass as ?cursor= to fetch the next page."}},"required":["data","has_more","next_cursor"],"additionalProperties":false},"example":{"data":[{"id":"f6a7b8c9-6666-4f7a-9b8c-d9e0f1a2b3c4","status":"approved","booking_type":"one_time","member_id":"a1b2c3d4-1111-4a2b-8c3d-e4f5a6b7c8d9","child":{"id":"a7b8c9d0-7777-4a8b-8c9d-e0f1a2b3c4d5","first_name":"Sample","last_name":"Child"},"start_date":null,"end_date":null,"booking_date":"2026-07-18","booking_start_time":"08:30:00","booking_end_time":"15:00:00","payment_amount":120,"payment_status":"pending","created_at":"2026-07-02T11:00:00+00:00","updated_at":"2026-07-03T09:40:00+00:00"}],"has_more":false,"next_cursor":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/bookings/{id}":{"get":{"operationId":"bookings.get","summary":"Get a booking","description":"Returns a single booking by id. Responds 404 if no such booking exists in your organization.\n\n**Scope:** `bookings:read`\n**Requires module:** `bookings`","tags":["Bookings"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Booking id."}}],"security":[{"apiKey":["bookings:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Booking id."},"status":{"type":"string","enum":["pending","approved","active","completed","cancelled"]},"booking_type":{"type":"string","enum":["one_time","recurring"]},"member_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The member (service provider) booked."},"child":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","first_name","last_name"],"additionalProperties":false},{"type":"null"}],"description":"The dependent this booking is for, when applicable."},"start_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"end_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}]},"booking_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"ISO 8601 date (YYYY-MM-DD)."},{"type":"null"}],"description":"Date of a one-time booking."},"booking_start_time":{"anyOf":[{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?$","description":"Time of day (HH:MM or HH:MM:SS)."},{"type":"null"}]},"booking_end_time":{"anyOf":[{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?$","description":"Time of day (HH:MM or HH:MM:SS)."},{"type":"null"}]},"payment_amount":{"anyOf":[{"type":"number"},{"type":"null"}]},"payment_status":{"type":"string","enum":["pending","paid","refunded","failed","not_required"]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","status","booking_type","member_id","child","start_date","end_date","booking_date","booking_start_time","booking_end_time","payment_amount","payment_status","created_at","updated_at"],"additionalProperties":false},"example":{"id":"f6a7b8c9-6666-4f7a-9b8c-d9e0f1a2b3c4","status":"approved","booking_type":"one_time","member_id":"a1b2c3d4-1111-4a2b-8c3d-e4f5a6b7c8d9","child":{"id":"a7b8c9d0-7777-4a8b-8c9d-e0f1a2b3c4d5","first_name":"Sample","last_name":"Child"},"start_date":null,"end_date":null,"booking_date":"2026-07-18","booking_start_time":"08:30:00","booking_end_time":"15:00:00","payment_amount":120,"payment_status":"pending","created_at":"2026-07-02T11:00:00+00:00","updated_at":"2026-07-03T09:40:00+00:00"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/webhook-endpoints":{"get":{"operationId":"webhooks.list","summary":"List webhook endpoints","description":"Returns the webhook endpoints configured for your organization in this key’s mode.\n\n**Scope:** `webhooks:read`","tags":["Webhooks"],"security":[{"apiKey":["webhooks:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"url":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"mode":{"type":"string","enum":["live","test"]},"enabled":{"type":"boolean"},"events":{"type":"array","items":{"type":"string"}},"secret_preview":{"type":"string","description":"Masked secret (\"whsec_…abcd\"). Reveal the full secret in the portal."},"consecutive_failures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"disabled_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"disabled_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_delivery_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"last_success_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","url","description","mode","enabled","events","secret_preview","consecutive_failures","disabled_at","disabled_reason","last_delivery_at","last_success_at","created_at","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean","description":"True when more results exist beyond this page."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass as ?cursor= to fetch the next page."}},"required":["data","has_more","next_cursor"],"additionalProperties":false},"example":{"data":[{"id":"aa11bb22-1111-4c33-8d44-e55f66a77b88","url":"https://example.com/webhooks","description":"Production receiver","mode":"live","enabled":true,"events":["member.created","member.verified"],"secret_preview":"whsec_…a1b2","consecutive_failures":0,"disabled_at":null,"disabled_reason":null,"last_delivery_at":null,"last_success_at":null,"created_at":"2026-07-01T10:00:00+00:00","updated_at":"2026-07-01T10:00:00+00:00"}],"has_more":false,"next_cursor":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"webhooks.create","summary":"Create a webhook endpoint","description":"Registers a webhook endpoint. The signing secret is returned once in the response. Subscribe with an array of event types or [\"*\"] for all.\n\n**Scope:** `webhooks:write`","tags":["Webhooks"],"security":[{"apiKey":["webhooks:write"]}],"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"url":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"mode":{"type":"string","enum":["live","test"]},"enabled":{"type":"boolean"},"events":{"type":"array","items":{"type":"string"}},"secret_preview":{"type":"string","description":"Masked secret (\"whsec_…abcd\"). Reveal the full secret in the portal."},"consecutive_failures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"disabled_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"disabled_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_delivery_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"last_success_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"secret":{"type":"string","description":"The signing secret, shown ONCE at creation. Store it securely."}},"required":["id","url","description","mode","enabled","events","secret_preview","consecutive_failures","disabled_at","disabled_reason","last_delivery_at","last_success_at","created_at","updated_at","secret"],"additionalProperties":false},"example":{"id":"aa11bb22-1111-4c33-8d44-e55f66a77b88","url":"https://example.com/webhooks","description":"Production receiver","mode":"live","enabled":true,"events":["member.created","member.verified"],"secret_preview":"whsec_…a1b2","consecutive_failures":0,"disabled_at":null,"disabled_reason":null,"last_delivery_at":null,"last_success_at":null,"created_at":"2026-07-01T10:00:00+00:00","updated_at":"2026-07-01T10:00:00+00:00","secret":"whsec_examplesecretvalue"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"HTTPS URL to receive events."},"description":{"type":"string"},"events":{"type":"array","items":{"type":"string"},"description":"Event types to subscribe to, or [\"*\"] for all."}},"required":["url","events"]},"example":{"url":"https://example.com/webhooks","events":["member.created"]}}}}}},"/v1/webhook-endpoints/{id}":{"get":{"operationId":"webhooks.get","summary":"Get a webhook endpoint","description":"Returns a single webhook endpoint by id.\n\n**Scope:** `webhooks:read`","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Webhook endpoint id."}}],"security":[{"apiKey":["webhooks:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"url":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"mode":{"type":"string","enum":["live","test"]},"enabled":{"type":"boolean"},"events":{"type":"array","items":{"type":"string"}},"secret_preview":{"type":"string","description":"Masked secret (\"whsec_…abcd\"). Reveal the full secret in the portal."},"consecutive_failures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"disabled_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"disabled_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_delivery_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"last_success_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","url","description","mode","enabled","events","secret_preview","consecutive_failures","disabled_at","disabled_reason","last_delivery_at","last_success_at","created_at","updated_at"],"additionalProperties":false},"example":{"id":"aa11bb22-1111-4c33-8d44-e55f66a77b88","url":"https://example.com/webhooks","description":"Production receiver","mode":"live","enabled":true,"events":["member.created","member.verified"],"secret_preview":"whsec_…a1b2","consecutive_failures":0,"disabled_at":null,"disabled_reason":null,"last_delivery_at":null,"last_success_at":null,"created_at":"2026-07-01T10:00:00+00:00","updated_at":"2026-07-01T10:00:00+00:00"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"webhooks.update","summary":"Update a webhook endpoint","description":"Updates a webhook endpoint’s URL, description, subscribed events, or enabled state. Re-enabling clears the auto-disable state.\n\n**Scope:** `webhooks:write`","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Webhook endpoint id."}}],"security":[{"apiKey":["webhooks:write"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"url":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"mode":{"type":"string","enum":["live","test"]},"enabled":{"type":"boolean"},"events":{"type":"array","items":{"type":"string"}},"secret_preview":{"type":"string","description":"Masked secret (\"whsec_…abcd\"). Reveal the full secret in the portal."},"consecutive_failures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"disabled_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"disabled_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_delivery_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"last_success_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","url","description","mode","enabled","events","secret_preview","consecutive_failures","disabled_at","disabled_reason","last_delivery_at","last_success_at","created_at","updated_at"],"additionalProperties":false},"example":{"id":"aa11bb22-1111-4c33-8d44-e55f66a77b88","url":"https://example.com/webhooks","description":"Production receiver","mode":"live","enabled":false,"events":["member.created","member.verified"],"secret_preview":"whsec_…a1b2","consecutive_failures":0,"disabled_at":null,"disabled_reason":null,"last_delivery_at":null,"last_success_at":null,"created_at":"2026-07-01T10:00:00+00:00","updated_at":"2026-07-01T10:00:00+00:00"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"}}},"example":{"enabled":false}}}}},"delete":{"operationId":"webhooks.delete","summary":"Delete a webhook endpoint","description":"Permanently deletes a webhook endpoint and its delivery history.\n\n**Scope:** `webhooks:write`","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Webhook endpoint id."}}],"security":[{"apiKey":["webhooks:write"]}],"responses":{"204":{"description":"No content."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/webhook-endpoints/{id}/roll-secret":{"post":{"operationId":"webhooks.rollSecret","summary":"Roll a webhook signing secret","description":"Generates a new signing secret and returns it once. The previous secret keeps signing for 24 hours so receivers can roll over without missing events.\n\n**Scope:** `webhooks:write`","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Webhook endpoint id."}}],"security":[{"apiKey":["webhooks:write"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"secret":{"type":"string","description":"The new signing secret (shown once)."}},"required":["secret"],"additionalProperties":false},"example":{"secret":"whsec_newexamplesecret"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}}}},"/v1/webhook-endpoints/{id}/test":{"post":{"operationId":"webhooks.test","summary":"Send a test event","description":"Sends a single test delivery of a real event type’s example payload (marked with X-Webhook-Test: true) and returns the immediate result.\n\n**Scope:** `webhooks:write`","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Webhook endpoint id."}}],"security":[{"apiKey":["webhooks:write"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"delivery_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ok":{"type":"boolean"},"response_status":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"duration_ms":{"type":"number"}},"required":["delivery_id","ok","response_status","duration_ms"],"additionalProperties":false},"example":{"delivery_id":"bb22cc33-2222-4d44-9e55-f66a77b88c99","ok":true,"response_status":200,"duration_ms":142}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_type":{"description":"Event type to send (defaults to a subscribed one).","type":"string"}}},"example":{"event_type":"member.created"}}}}}},"/v1/webhook-deliveries":{"get":{"operationId":"webhooks.listDeliveries","summary":"List webhook deliveries","description":"Returns recent webhook delivery attempts for your organization in this key’s mode. Filter by endpoint, status, or event type.\n\n**Scope:** `webhooks:read`","tags":["Webhooks"],"parameters":[{"name":"endpoint_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","processing","delivered","failed","dead"]}},{"name":"event_type","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"security":[{"apiKey":["webhooks:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"endpoint_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"event_id":{"type":"string"},"event_type":{"type":"string"},"mode":{"type":"string","enum":["live","test"]},"status":{"type":"string","enum":["pending","processing","delivered","failed","dead"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"last_response_status":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}]},"redelivery_of":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"delivered_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 timestamp."}},"required":["id","endpoint_id","event_id","event_type","mode","status","attempts","last_response_status","last_error","redelivery_of","delivered_at","created_at"],"additionalProperties":false}},"has_more":{"type":"boolean","description":"True when more results exist beyond this page."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass as ?cursor= to fetch the next page."}},"required":["data","has_more","next_cursor"],"additionalProperties":false},"example":{"data":[{"id":"bb22cc33-2222-4d44-9e55-f66a77b88c99","endpoint_id":"aa11bb22-1111-4c33-8d44-e55f66a77b88","event_id":"evt_9f1b6e9e11114222","event_type":"member.created","mode":"live","status":"delivered","attempts":1,"last_response_status":200,"last_error":null,"redelivery_of":null,"delivered_at":"2026-07-01T10:00:03+00:00","created_at":"2026-07-01T10:00:02+00:00"}],"has_more":false,"next_cursor":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/webhook-deliveries/{id}/redeliver":{"post":{"operationId":"webhooks.redeliver","summary":"Redeliver a webhook delivery","description":"Queues a fresh delivery of a previously-attempted event (same envelope id, so receivers can dedupe). Returns the new delivery id.\n\n**Scope:** `webhooks:write`","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Webhook delivery id."}}],"security":[{"apiKey":["webhooks:write"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"delivery_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["delivery_id"],"additionalProperties":false},"example":{"delivery_id":"cc33dd44-3333-4e55-8f66-a77b88c99d00"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}}}},"/v1/webhook-events":{"get":{"operationId":"webhooks.events","summary":"List available webhook events","description":"Returns the catalog of event types you can subscribe to, filtered to your organization’s active modules.\n\n**Scope:** `webhooks:read`","tags":["Webhooks"],"security":[{"apiKey":["webhooks:read"]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"module_gate":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","description","module_gate"],"additionalProperties":false}},"has_more":{"type":"boolean","description":"True when more results exist beyond this page."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass as ?cursor= to fetch the next page."}},"required":["data","has_more","next_cursor"],"additionalProperties":false},"example":{"data":[{"type":"member.created","description":"A member was created.","module_gate":"members"}],"has_more":false,"next_cursor":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"fcn_live_… / fcn_test_…","description":"Your API key as a bearer token. Live keys act on production data; test keys resolve to your sandbox."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}},"responses":{"BadRequest":{"description":"`invalid_request` — The request body, query, or path parameters failed validation. `details` lists each offending field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"`invalid_api_key` — The Authorization header is missing, malformed, or the key does not exist.\n\n`revoked_api_key` — The key was revoked. Create a new key in the Developer portal.\n\n`expired_api_key` — The key is past its expiry date (rolled keys expire 24 hours after rolling).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"`insufficient_scope` — The key is valid but lacks the scope this endpoint requires.\n\n`module_not_enabled` — The endpoint belongs to a module that is not active for this organization.\n\n`sandbox_unavailable` — A test-mode key was used but the organization has no sandbox. Create one from the portal, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"`not_found` — Unknown route, or the resource does not exist in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"`rate_limited` — Rate limit exceeded. Honor `Retry-After` and the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"x-scopes":{"members:read":"List and read members.","members:write":"Create, update, verify, and deactivate members.","customers:read":"List and read customers and sites.","customers:write":"Create and update customers and sites.","shifts:read":"List and read shifts and their assignments.","timesheets:read":"List and read timesheets (worked/billable time per assignment).","invoices:read":"List and read invoices and their line items.","bookings:read":"List and read bookings.","organization:read":"Read your organization profile.","webhooks:read":"List webhook endpoints and delivery history.","webhooks:write":"Manage webhook endpoints, secrets, and redeliveries."}}