[{"data":1,"prerenderedAt":977},["ShallowReactive",2],{"navigation":3,"\u002Fapi\u002Foverview":547,"\u002Fapi\u002Foverview-surround":972},[4,28,62,92,117,146,253,292,325,349,385,421,459,488],{"title":5,"path":6,"stem":7,"children":8,"icon":27},"Getting Started","\u002Fgetting-started","1.getting-started\u002F1.index",[9,12,17,22],{"title":10,"path":6,"stem":7,"icon":11},"Introduction","i-lucide-house",{"title":13,"path":14,"stem":15,"icon":16},"Usage","\u002Fgetting-started\u002Fusage","1.getting-started\u002F3.usage","i-lucide-sliders",{"title":18,"path":19,"stem":20,"icon":21},"Signing in on the mobile app","\u002Fgetting-started\u002Fmobile-app-sign-in","1.getting-started\u002F4.mobile-app-sign-in","i-lucide-smartphone",{"title":23,"path":24,"stem":25,"icon":26},"Running without email","\u002Fgetting-started\u002Frunning-without-email","1.getting-started\u002F5.running-without-email","i-lucide-mail-x",false,{"title":29,"icon":27,"path":30,"stem":31,"children":32,"page":27},"Security & Privacy","\u002Fsecurity","10.security",[33,38,43,47,52,57],{"title":34,"path":35,"stem":36,"icon":37},"Security Overview","\u002Fsecurity\u002Foverview","10.security\u002F1.overview","i-lucide-shield-check",{"title":39,"path":40,"stem":41,"icon":42},"Authentication","\u002Fsecurity\u002Fauthentication","10.security\u002F2.authentication","i-lucide-log-in",{"title":44,"path":45,"stem":46,"icon":21},"Two-Factor & Devices","\u002Fsecurity\u002Ftwo-factor-and-devices","10.security\u002F3.two-factor-and-devices",{"title":48,"path":49,"stem":50,"icon":51},"Audit & Monitoring","\u002Fsecurity\u002Faudit-and-monitoring","10.security\u002F4.audit-and-monitoring","i-lucide-scroll-text",{"title":53,"path":54,"stem":55,"icon":56},"Account Deletion & Privacy","\u002Fsecurity\u002Faccount-deletion-and-privacy","10.security\u002F5.account-deletion-and-privacy","i-lucide-user-x",{"title":58,"path":59,"stem":60,"icon":61},"Roles & Permissions","\u002Fsecurity\u002Froles-and-permissions","10.security\u002F6.roles-and-permissions","i-lucide-key-round",{"title":63,"icon":27,"path":64,"stem":65,"children":66,"page":27},"Billing & Plans","\u002Fbilling","11.billing",[67,72,77,82,87],{"title":68,"path":69,"stem":70,"icon":71},"Plans","\u002Fbilling\u002Fplans","11.billing\u002F1.plans","i-lucide-credit-card",{"title":73,"path":74,"stem":75,"icon":76},"Limits & Usage","\u002Fbilling\u002Flimits-and-usage","11.billing\u002F2.limits-and-usage","i-lucide-gauge",{"title":78,"path":79,"stem":80,"icon":81},"Managing Your Subscription","\u002Fbilling\u002Fmanaging-your-subscription","11.billing\u002F3.managing-your-subscription","i-lucide-receipt",{"title":83,"path":84,"stem":85,"icon":86},"Add-ons","\u002Fbilling\u002Fadd-ons","11.billing\u002F4.add-ons","i-lucide-puzzle",{"title":88,"path":89,"stem":90,"icon":91},"Integrations","\u002Fbilling\u002Fintegrations","11.billing\u002F5.integrations","i-lucide-plug",{"title":93,"icon":27,"path":94,"stem":95,"children":96,"page":27},"Settings","\u002Fsettings","12.settings",[97,101,105,109,113],{"title":98,"path":99,"stem":100},"General","\u002Fsettings\u002Fgeneral","12.settings\u002F1.general",{"title":102,"path":103,"stem":104},"Leave Types","\u002Fsettings\u002Fleavetype","12.settings\u002F2.leaveType",{"title":106,"path":107,"stem":108},"Carry Forward","\u002Fsettings\u002Fcarryforward","12.settings\u002F3.carryForward",{"title":110,"path":111,"stem":112},"Department Management","\u002Fsettings\u002Fdepartments","12.settings\u002F4.departments",{"title":114,"path":115,"stem":116},"Public Holidays","\u002Fsettings\u002Fpublicholiday","12.settings\u002F5.publicholiday",{"title":118,"path":119,"stem":120,"children":121,"page":27},"Mcp","\u002Fmcp","13.mcp",[122,127,131,136,141],{"title":123,"path":124,"stem":125,"icon":126},"Overview","\u002Fmcp\u002Foverview","13.mcp\u002F1.overview","i-lucide-bot",{"title":128,"path":129,"stem":130,"icon":91},"Connecting","\u002Fmcp\u002Fconnecting","13.mcp\u002F2.connecting",{"title":132,"path":133,"stem":134,"icon":135},"Tools Reference","\u002Fmcp\u002Ftools","13.mcp\u002F3.tools","i-lucide-wrench",{"title":137,"path":138,"stem":139,"icon":140},"Security","\u002Fmcp\u002Fsecurity","13.mcp\u002F4.security","i-lucide-shield",{"title":142,"path":143,"stem":144,"icon":145},"Integrating Your Own MCP Client","\u002Fmcp\u002Fcustom-client","13.mcp\u002F5.custom-client","i-lucide-code",{"title":147,"icon":27,"path":148,"stem":149,"children":150,"page":27},"Public API","\u002Fapi","14.api",[151,156,160,164,169,174,179,183,208,238,243,248],{"title":152,"path":153,"stem":154,"icon":155},"API Overview","\u002Fapi\u002Foverview","14.api\u002F1.overview","i-lucide-code-xml",{"title":5,"path":157,"stem":158,"icon":159},"\u002Fapi\u002Fgetting-started","14.api\u002F2.getting-started","i-lucide-rocket",{"title":161,"path":162,"stem":163,"icon":61},"Authentication & Tokens","\u002Fapi\u002Fauthentication","14.api\u002F3.authentication",{"title":165,"path":166,"stem":167,"icon":168},"API Roles & Scopes","\u002Fapi\u002Froles-and-scopes","14.api\u002F4.roles-and-scopes","i-lucide-layers",{"title":170,"path":171,"stem":172,"icon":173},"Requests & Responses","\u002Fapi\u002Frequests-and-responses","14.api\u002F5.requests-and-responses","i-lucide-arrow-left-right",{"title":175,"path":176,"stem":177,"icon":178},"Errors","\u002Fapi\u002Ferrors","14.api\u002F6.errors","i-lucide-circle-alert",{"title":180,"path":181,"stem":182,"icon":76},"Rate Limits","\u002Fapi\u002Frate-limits","14.api\u002F7.rate-limits",{"title":184,"icon":185,"path":186,"stem":187,"children":188,"page":27},"Guides","i-lucide-book-marked","\u002Fapi\u002Fguides","14.api\u002F8.guides",[189,194,199,204],{"title":190,"path":191,"stem":192,"icon":193},"People","\u002Fapi\u002Fguides\u002Fpeople","14.api\u002F8.guides\u002F1.people","i-lucide-users",{"title":195,"path":196,"stem":197,"icon":198},"Leave","\u002Fapi\u002Fguides\u002Fleave","14.api\u002F8.guides\u002F2.leave","i-lucide-calendar-days",{"title":200,"path":201,"stem":202,"icon":203},"Time","\u002Fapi\u002Fguides\u002Ftime","14.api\u002F8.guides\u002F3.time","i-lucide-clock",{"title":205,"path":206,"stem":207,"icon":81},"Expenses & Documents","\u002Fapi\u002Fguides\u002Fexpenses-and-documents","14.api\u002F8.guides\u002F4.expenses-and-documents",{"title":209,"icon":210,"path":211,"stem":212,"children":213,"page":27},"Webhooks","i-lucide-webhook","\u002Fapi\u002Fwebhooks","14.api\u002F9.webhooks",[214,218,223,228,233],{"title":215,"path":216,"stem":217,"icon":210},"Webhooks Overview","\u002Fapi\u002Fwebhooks\u002Foverview","14.api\u002F9.webhooks\u002F1.overview",{"title":219,"path":220,"stem":221,"icon":222},"Events Reference","\u002Fapi\u002Fwebhooks\u002Fevents","14.api\u002F9.webhooks\u002F2.events","i-lucide-list",{"title":224,"path":225,"stem":226,"icon":227},"Verifying Signatures","\u002Fapi\u002Fwebhooks\u002Fverifying-signatures","14.api\u002F9.webhooks\u002F3.verifying-signatures","i-lucide-badge-check",{"title":229,"path":230,"stem":231,"icon":232},"Retries & Failures","\u002Fapi\u002Fwebhooks\u002Fretries-and-failures","14.api\u002F9.webhooks\u002F4.retries-and-failures","i-lucide-refresh-cw",{"title":234,"path":235,"stem":236,"icon":237},"Best Practices","\u002Fapi\u002Fwebhooks\u002Fbest-practices","14.api\u002F9.webhooks\u002F5.best-practices","i-lucide-list-checks",{"title":239,"path":240,"stem":241,"icon":242},"Postman & OpenAPI","\u002Fapi\u002Fpostman-and-openapi","14.api\u002F91.postman-and-openapi","i-lucide-file-json",{"title":244,"path":245,"stem":246,"icon":247},"Versioning & Changes","\u002Fapi\u002Fversioning","14.api\u002F92.versioning","i-lucide-git-branch",{"title":249,"path":250,"stem":251,"icon":252},"API Reference","\u002Fapi\u002Freference","14.api\u002F93.reference","i-lucide-book-open",{"title":254,"icon":27,"path":255,"stem":256,"children":257,"page":27},"Data Import & Migration","\u002Fdata-import","2.data-import",[258,262,267,272,277,282,287],{"title":123,"path":259,"stem":260,"icon":261},"\u002Fdata-import\u002Foverview","2.data-import\u002F1.overview","i-lucide-database",{"title":263,"path":264,"stem":265,"icon":266},"Importing a File","\u002Fdata-import\u002Fimporting-a-file","2.data-import\u002F2.importing-a-file","i-lucide-file-up",{"title":268,"path":269,"stem":270,"icon":271},"Supported Platforms","\u002Fdata-import\u002Fsupported-platforms","2.data-import\u002F3.supported-platforms","i-lucide-layout-grid",{"title":273,"path":274,"stem":275,"icon":276},"Direct Connections","\u002Fdata-import\u002Fdirect-connections","2.data-import\u002F4.direct-connections","i-lucide-plug-zap",{"title":278,"path":279,"stem":280,"icon":281},"Custom Templates","\u002Fdata-import\u002Fcustom-templates","2.data-import\u002F5.custom-templates","i-lucide-layout-template",{"title":283,"path":284,"stem":285,"icon":286},"Rollback & Import History","\u002Fdata-import\u002Frollback-and-history","2.data-import\u002F6.rollback-and-history","i-lucide-undo-2",{"title":288,"path":289,"stem":290,"icon":291},"Troubleshooting","\u002Fdata-import\u002Ftroubleshooting","2.data-import\u002F7.troubleshooting","i-lucide-life-buoy",{"title":293,"icon":27,"path":294,"stem":295,"children":296,"page":27},"Leave Management","\u002Fleave-management","3.leave-management",[297,302,307,312,316,321],{"title":298,"path":299,"stem":300,"icon":301},"Leave Management Overview","\u002Fleave-management\u002Foverview","3.leave-management\u002F1.overview","i-lucide-palmtree",{"title":303,"path":304,"stem":305,"icon":306},"Requesting Leave","\u002Fleave-management\u002Frequesting-leave","3.leave-management\u002F2.requesting-leave","i-lucide-calendar-plus",{"title":308,"path":309,"stem":310,"icon":311},"Leave Balances","\u002Fleave-management\u002Fleave-balances","3.leave-management\u002F3.leave-balances","i-lucide-wallet",{"title":313,"path":314,"stem":315,"icon":193},"Group Booking","\u002Fleave-management\u002Fgroup-booking","3.leave-management\u002F4.group-booking",{"title":317,"path":318,"stem":319,"icon":320},"Editing and Cancelling Leave","\u002Fleave-management\u002Fediting-and-cancelling","3.leave-management\u002F5.editing-and-cancelling","i-lucide-pencil",{"title":322,"path":323,"stem":324,"icon":291},"Leave Troubleshooting","\u002Fleave-management\u002Ftroubleshooting","3.leave-management\u002F6.troubleshooting",{"title":326,"icon":27,"path":327,"stem":328,"children":329,"page":27},"Approvals","\u002Fapprovals","4.approvals",[330,335,340,344],{"title":331,"path":332,"stem":333,"icon":334},"Approvals Overview","\u002Fapprovals\u002Foverview","4.approvals\u002F1.overview","i-lucide-check-check",{"title":336,"path":337,"stem":338,"icon":339},"Leave Approvals","\u002Fapprovals\u002Fleave-approvals","4.approvals\u002F2.leave-approvals","i-lucide-calendar-check",{"title":341,"path":342,"stem":343,"icon":81},"Expense Approvals","\u002Fapprovals\u002Fexpense-approvals","4.approvals\u002F3.expense-approvals",{"title":345,"path":346,"stem":347,"icon":348},"Time Approvals","\u002Fapprovals\u002Ftime-approvals","4.approvals\u002F4.time-approvals","i-lucide-clock-9",{"title":350,"icon":27,"path":351,"stem":352,"children":353,"page":27},"Time tracking & monitoring","\u002Ftime-tracking","5.Time Tracking",[354,359,364,369,373,377,381],{"title":355,"path":356,"stem":357,"icon":358},"Clocking In & Location","\u002Ftime-tracking\u002Fclock-in-and-location","5.Time Tracking\u002F5.clock-in-and-location","i-lucide-map-pin",{"title":360,"path":361,"stem":362,"icon":363},"Overtime & Pay-Period Lockdown","\u002Ftime-tracking\u002Fovertime-and-lockdown","5.Time Tracking\u002F6.overtime-and-lockdown","i-lucide-lock",{"title":365,"path":366,"stem":367,"icon":368},"Geofencing","\u002Ftime-tracking\u002Fgeofencing","5.Time Tracking\u002F7.geofencing","i-lucide-map",{"title":370,"path":371,"stem":372},"Time & Projects","\u002Ftime-tracking\u002Ftimeandprojects","5.Time Tracking\u002FTime&Projects",{"title":374,"path":375,"stem":376},"Time Tracking","\u002Ftime-tracking\u002Ftime-tracking","5.Time Tracking\u002FTime-tracking",{"title":378,"path":379,"stem":380},"Timeboard","\u002Ftime-tracking\u002Ftimeboard","5.Time Tracking\u002FTimeBoard",{"title":382,"path":383,"stem":384},"Timesheets","\u002Ftime-tracking\u002Ftimesheets","5.Time Tracking\u002FTimesheets",{"title":386,"icon":27,"path":387,"stem":388,"children":389,"page":27},"Expenses","\u002Fexpenses","6.expenses",[390,394,398,402,406,411,416],{"title":391,"path":392,"stem":393},"Expense Claims","\u002Fexpenses\u002Foverview","6.expenses\u002F1.overview",{"title":395,"path":396,"stem":397},"Add & Manage Purchases","\u002Fexpenses\u002Fpurchases","6.expenses\u002F2.purchases",{"title":399,"path":400,"stem":401},"Travel & Mileage Entry","\u002Fexpenses\u002Ftravelentries","6.expenses\u002F3.travelentries",{"title":403,"path":404,"stem":405,"icon":71},"Company Card Expenses","\u002Fexpenses\u002Fcompany-cards","6.expenses\u002F4.company-cards",{"title":407,"path":408,"stem":409,"icon":410},"Per Diems","\u002Fexpenses\u002Fper-diems","6.expenses\u002F5.per-diems","i-lucide-utensils",{"title":412,"path":413,"stem":414,"icon":415},"Receipt Scanning","\u002Fexpenses\u002Freceipt-scanning","6.expenses\u002F6.receipt-scanning","i-lucide-scan-line",{"title":417,"path":418,"stem":419,"icon":420},"Statuses & Submission","\u002Fexpenses\u002Fstatuses-and-submission","6.expenses\u002F7.statuses-and-submission","i-lucide-git-pull-request-arrow",{"title":422,"icon":27,"path":423,"stem":424,"children":425,"page":27},"Documents & E-Signatures","\u002Fdocuments","7.documents",[426,430,435,440,445,449,454],{"title":123,"path":427,"stem":428,"icon":429},"\u002Fdocuments\u002Foverview","7.documents\u002F1.overview","i-lucide-folder-open",{"title":431,"path":432,"stem":433,"icon":434},"Uploading Documents","\u002Fdocuments\u002Fuploading","7.documents\u002F2.uploading","i-lucide-upload",{"title":436,"path":437,"stem":438,"icon":439},"E-Signatures","\u002Fdocuments\u002Fe-signatures","7.documents\u002F3.e-signatures","i-lucide-pen-tool",{"title":441,"path":442,"stem":443,"icon":444},"Audit Trail & Certificate","\u002Fdocuments\u002Faudit-trail","7.documents\u002F4.audit-trail","i-lucide-file-check",{"title":446,"path":447,"stem":448,"icon":281},"Templates & Bulk Send","\u002Fdocuments\u002Ftemplates-and-bulk-send","7.documents\u002F5.templates-and-bulk-send",{"title":450,"path":451,"stem":452,"icon":453},"Onboarding","\u002Fdocuments\u002Fonboarding","7.documents\u002F6.onboarding","i-lucide-user-plus",{"title":455,"path":456,"stem":457,"icon":458},"Offboarding","\u002Fdocuments\u002Foffboarding","7.documents\u002F7.offboarding","i-lucide-user-minus",{"title":460,"icon":27,"path":461,"stem":462,"children":463,"page":27},"People & HR","\u002Fpeople","8.people",[464,468,473,478,483],{"title":465,"path":466,"stem":467,"icon":193},"Directory & Profiles","\u002Fpeople\u002Fdirectory-and-profiles","8.people\u002F1.directory-and-profiles",{"title":469,"path":470,"stem":471,"icon":472},"Managing Users","\u002Fpeople\u002Fmanaging-users","8.people\u002F2.managing-users","i-lucide-user-cog",{"title":474,"path":475,"stem":476,"icon":477},"HR Records","\u002Fpeople\u002Fhr-records","8.people\u002F3.hr-records","i-lucide-folder-archive",{"title":479,"path":480,"stem":481,"icon":482},"Performance","\u002Fpeople\u002Fperformance","8.people\u002F4.performance","i-lucide-target",{"title":484,"path":485,"stem":486,"icon":487},"Training","\u002Fpeople\u002Ftraining","8.people\u002F5.training","i-lucide-graduation-cap",{"title":489,"icon":27,"path":490,"stem":491,"children":492,"page":27},"Features","\u002Ffeatures","9.features",[493,497,501,505,510,515,519,523,527,531,535,539,543],{"title":494,"path":495,"stem":496,"icon":11},"Home","\u002Ffeatures\u002Fhome","9.features\u002F1.home",{"title":498,"path":499,"stem":500},"Email Configuration (SMTP)","\u002Ffeatures\u002Femail-configuration","9.features\u002F10.email-configuration",{"title":502,"path":503,"stem":504},"SMTP troubleshoot","\u002Ffeatures\u002Fsmtp-troubleshoot","9.features\u002F11.smtp-troubleshoot",{"title":506,"path":507,"stem":508,"icon":509},"Notifications","\u002Ffeatures\u002Fnotifications","9.features\u002F12.notifications","i-lucide-bell",{"title":511,"path":512,"stem":513,"icon":514},"Reports","\u002Ffeatures\u002Freports","9.features\u002F13.reports","i-lucide-bar-chart-3",{"title":516,"path":517,"stem":518},"Dashboard","\u002Ffeatures\u002Fdashboard","9.features\u002F2.dashboard",{"title":520,"path":521,"stem":522},"Calendar & Leave Overview","\u002Ffeatures\u002Fcalendar","9.features\u002F3.calendar",{"title":524,"path":525,"stem":526},"Calendar Integration","\u002Ffeatures\u002Fcalendar-integration","9.features\u002F4.calendar-integration",{"title":528,"path":529,"stem":530},"Schedules","\u002Ffeatures\u002Fschedules","9.features\u002F5.schedules",{"title":532,"path":533,"stem":534},"Project Management","\u002Ffeatures\u002Fprojects","9.features\u002F6.projects",{"title":536,"path":537,"stem":538},"Expense Settings","\u002Ffeatures\u002Fexpense-settings","9.features\u002F7.expense-settings",{"title":540,"path":541,"stem":542},"Auth0 SSO Integration","\u002Ffeatures\u002Fauth0-integration","9.features\u002F8.auth0-integration",{"title":544,"path":545,"stem":546},"Password & Authentication Policy","\u002Ffeatures\u002Fpolicies","9.features\u002F9.policies",{"id":548,"title":152,"body":549,"description":965,"extension":966,"links":967,"meta":968,"navigation":969,"path":153,"seo":970,"stem":154,"__hash__":971},"docs\u002F14.api\u002F1.overview.md",{"type":550,"value":551,"toc":956},"minimark",[552,556,561,564,575,586,589,593,685,692,696,699,742,749,753,830,833,837,950],[553,554,555],"p",{},"The BookYourPTO REST API lets your own scripts, internal systems and integration tools (iPaaS platforms such as Zapier, Make or Workato) read and work with your organization's data. It is a second way into the same data you see in the app, held to the same rules: anything a token can see or do, the person who owns it could already see or do in BookYourPTO.",[557,558,560],"h2",{"id":559},"base-url","Base URL",[553,562,563],{},"Every endpoint lives under one base URL:",[565,566,571],"pre",{"className":567,"code":569,"language":570},[568],"language-text","https:\u002F\u002Fapp.bookyourpto.com\u002Fapi\u002Fv1\n","text",[572,573,569],"code",{"__ignoreMap":574},"",[553,576,577,578,581,582,585],{},"If your organization uses a custom domain, ",[572,579,580],{},"GET \u002Forganization"," returns the base URL to use in its ",[572,583,584],{},"base_url"," field.",[553,587,588],{},"All requests and responses use JSON over HTTPS. The API is designed for server-to-server use: it sends no CORS headers, so a web page on another site cannot call it from a browser. Call it from your own back end, a scheduled job or an integration platform.",[557,590,592],{"id":591},"who-can-use-the-api","Who can use the API",[594,595,596,609],"table",{},[597,598,599],"thead",{},[600,601,602,606],"tr",{},[603,604,605],"th",{},"Requirement",[603,607,608],{},"Detail",[610,611,612,636,658,675],"tbody",{},[600,613,614,621],{},[615,616,617],"td",{},[618,619,620],"strong",{},"Plan",[615,622,623,624,627,628,631,632,635],{},"API access is included in every paid plan: ",[618,625,626],{},"Pro",", ",[618,629,630],{},"Business"," and ",[618,633,634],{},"Enterprise",". It is not available on the Free plan.",[600,637,638,643],{},[615,639,640],{},[618,641,642],{},"Organization switch",[615,644,645,646,649,650,653,654,657],{},"The API is ",[618,647,648],{},"off"," by default. An ",[618,651,652],{},"Executive"," switches it on under ",[618,655,656],{},"Settings > API > Settings",". While it is off, every token is refused and no new tokens can be created.",[600,659,660,665],{},[615,661,662],{},[618,663,664],{},"Who may create tokens",[615,666,667,668,631,671,674],{},"By default ",[618,669,670],{},"Administrators",[618,672,673],{},"Executives",". An Executive can allow other roles to create personal tokens for themselves.",[600,676,677,682],{},[615,678,679],{},[618,680,681],{},"Subscription in good standing",[615,683,684],{},"A subscription that is past due, suspended, cancelled or unpaid stops every token until it is resolved.",[553,686,687,688,691],{},"These conditions are checked again on ",[618,689,690],{},"every request",", not only when a token is created. Downgrading to Free, switching the API off, or a lapsed subscription stops all tokens at once.",[557,693,695],{"id":694},"a-token-acts-as-its-owner","A token acts as its owner",[553,697,698],{},"Every API token is owned by one person in your organization. On each request the token acts as that person:",[700,701,702,709,720,726,736],"ul",{},[703,704,705,708],"li",{},[618,706,707],{},"Visibility is the owner's."," A department head's token sees what that department head sees in the app; an employee's token sees what that employee sees. Privacy settings, private leave types and department restrictions apply exactly as they do in the app.",[703,710,711,714,715,719],{},[618,712,713],{},"Scopes narrow it further."," A token only reaches the areas its ",[716,717,718],"a",{"href":166},"scopes"," allow. A scope never widens what the owner could do.",[703,721,722,725],{},[618,723,724],{},"The owner's role sets a ceiling."," Each scope has a minimum role. A token cannot hold a scope above its owner's role, and if the owner is later demoted, scopes above the new role stop working on the next request.",[703,727,728,731,732,735],{},[618,729,730],{},"The owner's account must stay in good standing."," If the owner is deactivated or offboarded, or is no longer in a role allowed to hold tokens, the token stops working immediately. Offboarding revokes the owner's tokens permanently. See ",[716,733,161],{"href":734},"\u002Fapi\u002Fauthentication#when-a-token-stops-working",".",[703,737,738,741],{},[618,739,740],{},"Writes follow the app's rules."," A request made through the API goes through the same business rules as the same action in the app: notice periods, balances, locked dates, approval chains, notifications and calendar sync. Every write is recorded in the organization's audit log with the token that made it.",[743,744,746],"callout",{"color":745,"icon":37},"blue",[553,747,748],{},"Because the token is bound to a person, choose the owner deliberately. For an organization-wide integration, a token owned by an Administrator with only the scopes the integration needs is usually the right shape.",[557,750,752],{"id":751},"what-you-can-do-with-it","What you can do with it",[594,754,755,768],{},[597,756,757],{},[600,758,759,762,765],{},[603,760,761],{},"Area",[603,763,764],{},"Read",[603,766,767],{},"Write",[610,769,770,782,794,806,818],{},[600,771,772,776,779],{},[615,773,774],{},[716,775,190],{"href":191},[615,777,778],{},"The directory, employment details, departments, teams, training, certifications, equipment, benefits, compensation, custom fields, goals and onboarding checklists",[615,780,781],{},"Add and update people, departments and teams; assign training; issue and update equipment",[600,783,784,788,791],{},[615,785,786],{},[716,787,195],{"href":196},[615,789,790],{},"Leave types, requests, balances, public holidays and locked dates",[615,792,793],{},"Request and cancel leave; approve and reject requests and cancellation requests",[600,795,796,800,803],{},[615,797,798],{},[716,799,200],{"href":201},[615,801,802],{},"Time entries, timesheets, projects, tasks, clients and shifts",[615,804,805],{},"Create, edit and delete time entries; approve and reject them",[600,807,808,812,815],{},[615,809,810],{},[716,811,205],{"href":206},[615,813,814],{},"Expense reports with their line items, and document metadata, signers and files",[615,816,817],{},"Approve and reject expense reports",[600,819,820,824,827],{},[615,821,822],{},[716,823,209],{"href":216},[615,825,826],{},"Endpoints, delivery logs and the event catalogue",[615,828,829],{},"Subscribe to events, test and redeliver",[553,831,832],{},"Some things are deliberately not available through the API: clocking in and out (location and geofence checks belong to the device), signing documents (a signature is a legal act bound to a person), billing, single sign-on, custom domains and imports.",[557,834,836],{"id":835},"what-is-in-this-section","What is in this section",[594,838,839,849],{},[597,840,841],{},[600,842,843,846],{},[603,844,845],{},"Page",[603,847,848],{},"What it covers",[610,850,851,860,869,878,887,896,905,914,923,932,941],{},[600,852,853,857],{},[615,854,855],{},[716,856,5],{"href":157},[615,858,859],{},"Switch the API on, create a token and make a first request",[600,861,862,866],{},[615,863,864],{},[716,865,161],{"href":162},[615,867,868],{},"Token format, expiry, rotation, revocation and IP allowlists",[600,870,871,875],{},[615,872,873],{},[716,874,165],{"href":166},[615,876,877],{},"Reusable API roles, the built-in templates and the scope catalogue",[600,879,880,884],{},[615,881,882],{},[716,883,170],{"href":171},[615,885,886],{},"The response envelope, field naming, dates, pagination and idempotency",[600,888,889,893],{},[615,890,891],{},[716,892,175],{"href":176},[615,894,895],{},"Every error code and what to do about it",[600,897,898,902],{},[615,899,900],{},[716,901,180],{"href":181},[615,903,904],{},"The limits, the headers that report them and how to back off",[600,906,907,911],{},[615,908,909],{},[716,910,184],{"href":191},[615,912,913],{},"Common tasks for people, leave, time, expenses and documents, with visibility rules and gotchas",[600,915,916,920],{},[615,917,918],{},[716,919,209],{"href":216},[615,921,922],{},"Receiving events instead of polling",[600,924,925,929],{},[615,926,927],{},[716,928,239],{"href":240},[615,930,931],{},"Downloading the specification and the Postman collection",[600,933,934,938],{},[615,935,936],{},[716,937,244],{"href":245},[615,939,940],{},"What can change within the API and how breaking changes are handled",[600,942,943,947],{},[615,944,945],{},[716,946,249],{"href":250},[615,948,949],{},"Every endpoint, its parameters and its response schema",[553,951,952,953,955],{},"The ",[716,954,249],{"href":250}," is generated from the API itself, so it always lists exactly the endpoints that are available. The guides in this section describe the rules every endpoint shares and walk through common tasks.",{"title":574,"searchDepth":957,"depth":958,"links":959},1,2,[960,961,962,963,964],{"id":559,"depth":958,"text":560},{"id":591,"depth":958,"text":592},{"id":694,"depth":958,"text":695},{"id":751,"depth":958,"text":752},{"id":835,"depth":958,"text":836},"What the BookYourPTO REST API is for, who can use it, the base URL, and the rule that a token can never do more than the person who owns it.","md",null,{},{"icon":155},{"title":152,"description":965},"nAWUswnbcIkXPvmD9_TBozm6vAlueOjuePihihbG-Ow",[973,975],{"title":142,"path":143,"stem":144,"description":974,"icon":145,"children":-1},"Build a custom MCP client that connects to the BookYourPTO MCP server using the Streamable HTTP transport.",{"title":5,"path":157,"stem":158,"description":976,"icon":159,"children":-1},"Switch the API on, create your first token in Settings > API, make a request with curl and read the response.",1791906527744]