[{"data":1,"prerenderedAt":1425},["ShallowReactive",2],{"navigation":3,"\u002Fapi\u002Fgetting-started":547,"\u002Fapi\u002Fgetting-started-surround":1420},[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":5,"body":549,"description":1413,"extension":1414,"links":1415,"meta":1416,"navigation":1417,"path":157,"seo":1418,"stem":158,"__hash__":1419},"docs\u002F14.api\u002F2.getting-started.md",{"type":550,"value":551,"toc":1405},"minimark",[552,556,561,576,580,621,629,633,695,707,713,717,729,774,1161,1170,1176,1202,1206,1209,1245,1339,1349,1353,1401],[553,554,555],"p",{},"This guide takes you from an organization with the API switched off to a working request in a few minutes.",[557,558,560],"h2",{"id":559},"before-you-begin","Before you begin",[562,563,564,568],"ul",{},[565,566,567],"li",{},"Your organization is on a paid plan (Pro, Business or Enterprise).",[565,569,570,571,575],{},"To switch the API on you need the ",[572,573,574],"strong",{},"Executive"," role. To create a token you need a role your organization allows to create tokens (Administrators and Executives by default).",[557,577,579],{"id":578},"_1-switch-the-api-on","1. Switch the API on",[581,582,583,593,600],"ol",{},[565,584,585,586,589,590,592],{},"Go to ",[572,587,588],{},"Settings > API"," and open the ",[572,591,93],{}," tab.",[565,594,595,596,599],{},"Turn on ",[572,597,598],{},"Enable the API",".",[565,601,602,603],{},"Optionally adjust the other two settings on the same tab:\n",[562,604,605,615],{},[565,606,607,610,611,614],{},[572,608,609],{},"Maximum token lifetime"," — every token must expire within this many days of being created. It can be between 1 and 365 days and defaults to ",[572,612,613],{},"90",". Lowering it does not shorten tokens that already exist.",[565,616,617,620],{},[572,618,619],{},"Who may create tokens"," — the roles allowed to hold and create tokens. Administrators and Executives by default.",[622,623,626],"callout",{"color":624,"icon":625},"blue","i-lucide-info",[553,627,628],{},"Only Executives can change these settings. Administrators can see the API page and manage tokens and API roles, but the switch itself belongs to an Executive.",[557,630,632],{"id":631},"_2-create-a-token","2. Create a token",[581,634,635,645,652,659,677,684,690],{},[565,636,637,638,641,642,599],{},"On the ",[572,639,640],{},"Tokens"," tab, click ",[572,643,644],{},"Create token",[565,646,647,648,651],{},"Give it a ",[572,649,650],{},"Name"," that says what uses it, such as \"Payroll export\" or \"HRIS nightly sync\".",[565,653,654,655,658],{},"Choose its ",[572,656,657],{},"Owner",". It defaults to you. Administrators and Executives can create a token for someone else, but only for a person whose role is below their own; a colleague in the same role creates their own token.",[565,660,661,662,665,666,669,670,673,674,599],{},"Under ",[572,663,664],{},"Access",", either pick an ",[572,667,668],{},"API role"," or choose ",[572,671,672],{},"custom scopes",". Grant only what the integration needs. See ",[675,676,165],"a",{"href":166},[565,678,679,680,683],{},"Choose when it ",[572,681,682],{},"Expires",": a preset (7, 30, 60, 90, 180 or 365 days, limited to your organization's maximum) or a specific date. A date means the end of that day in your timezone.",[565,685,686,687,599],{},"Optionally restrict it to ",[572,688,689],{},"Allowed IP addresses",[565,691,692,693,599],{},"Click ",[572,694,644],{},[553,696,697,698,701,702,706],{},"The token is shown ",[572,699,700],{},"once",". Copy it into your secret store now; it cannot be displayed again. If it is lost, ",[675,703,705],{"href":704},"\u002Fapi\u002Fauthentication#rotating-a-token","rotate"," the token to get a new secret.",[553,708,709,710,599],{},"Team members whose role is allowed to create tokens, but who are not Administrators or Executives, find their own tokens under ",[572,711,712],{},"Settings > Personal API Tokens",[557,714,716],{"id":715},"_3-make-your-first-request","3. Make your first request",[553,718,719,720,724,725,728],{},"Send the token in the ",[721,722,723],"code",{},"Authorization"," header. Start with ",[721,726,727],{},"GET \u002Ftoken",", which needs no particular scope and tells you what the token can do:",[730,731,736],"pre",{"className":732,"code":733,"language":734,"meta":735,"style":735},"language-bash shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","curl https:\u002F\u002Fapp.bookyourpto.com\u002Fapi\u002Fv1\u002Ftoken \\\n  -H \"Authorization: Bearer $BOOKYOURPTO_TOKEN\"\n","bash","",[721,737,738,755],{"__ignoreMap":735},[739,740,743,747,751],"span",{"class":741,"line":742},"line",1,[739,744,746],{"class":745},"sBMFI","curl",[739,748,750],{"class":749},"sfazB"," https:\u002F\u002Fapp.bookyourpto.com\u002Fapi\u002Fv1\u002Ftoken",[739,752,754],{"class":753},"sTEyZ"," \\\n",[739,756,758,761,765,768,771],{"class":741,"line":757},2,[739,759,760],{"class":749},"  -H",[739,762,764],{"class":763},"sMK4o"," \"",[739,766,767],{"class":749},"Authorization: Bearer ",[739,769,770],{"class":753},"$BOOKYOURPTO_TOKEN",[739,772,773],{"class":763},"\"\n",[730,775,779],{"className":776,"code":777,"language":778,"meta":735,"style":735},"language-json shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","{\n  \"data\": {\n    \"id\": \"cm...\",\n    \"name\": \"Payroll export\",\n    \"prefix\": \"pat_Xy3kQ9Lm\",\n    \"api_role\": { \"id\": \"cm...\", \"name\": \"Time and payroll export\" },\n    \"owner\": {\n      \"id\": \"cm...\",\n      \"first_name\": \"Dana\",\n      \"last_name\": \"Okafor\",\n      \"email\": \"dana@example.com\",\n      \"role\": \"ADMINISTRATOR\"\n    },\n    \"scopes\": [\"organization:read\", \"users:read\"],\n    \"expires_at\": \"2027-01-10T07:59:59.999Z\",\n    \"created_at\": \"2026-10-12T16:20:41.118Z\"\n  },\n  \"meta\": { \"request_id\": \"8f2c4b1e-...\" }\n}\n","json",[721,780,781,786,804,827,848,869,920,934,954,975,996,1017,1036,1042,1076,1097,1116,1122,1155],{"__ignoreMap":735},[739,782,783],{"class":741,"line":742},[739,784,785],{"class":763},"{\n",[739,787,788,791,795,798,801],{"class":741,"line":757},[739,789,790],{"class":763},"  \"",[739,792,794],{"class":793},"spNyl","data",[739,796,797],{"class":763},"\"",[739,799,800],{"class":763},":",[739,802,803],{"class":763}," {\n",[739,805,807,810,813,815,817,819,822,824],{"class":741,"line":806},3,[739,808,809],{"class":763},"    \"",[739,811,812],{"class":745},"id",[739,814,797],{"class":763},[739,816,800],{"class":763},[739,818,764],{"class":763},[739,820,821],{"class":749},"cm...",[739,823,797],{"class":763},[739,825,826],{"class":763},",\n",[739,828,830,832,835,837,839,841,844,846],{"class":741,"line":829},4,[739,831,809],{"class":763},[739,833,834],{"class":745},"name",[739,836,797],{"class":763},[739,838,800],{"class":763},[739,840,764],{"class":763},[739,842,843],{"class":749},"Payroll export",[739,845,797],{"class":763},[739,847,826],{"class":763},[739,849,851,853,856,858,860,862,865,867],{"class":741,"line":850},5,[739,852,809],{"class":763},[739,854,855],{"class":745},"prefix",[739,857,797],{"class":763},[739,859,800],{"class":763},[739,861,764],{"class":763},[739,863,864],{"class":749},"pat_Xy3kQ9Lm",[739,866,797],{"class":763},[739,868,826],{"class":763},[739,870,872,874,877,879,881,884,886,889,891,893,895,897,899,902,904,906,908,910,912,915,917],{"class":741,"line":871},6,[739,873,809],{"class":763},[739,875,876],{"class":745},"api_role",[739,878,797],{"class":763},[739,880,800],{"class":763},[739,882,883],{"class":763}," {",[739,885,764],{"class":763},[739,887,812],{"class":888},"sbssI",[739,890,797],{"class":763},[739,892,800],{"class":763},[739,894,764],{"class":763},[739,896,821],{"class":749},[739,898,797],{"class":763},[739,900,901],{"class":763},",",[739,903,764],{"class":763},[739,905,834],{"class":888},[739,907,797],{"class":763},[739,909,800],{"class":763},[739,911,764],{"class":763},[739,913,914],{"class":749},"Time and payroll export",[739,916,797],{"class":763},[739,918,919],{"class":763}," },\n",[739,921,923,925,928,930,932],{"class":741,"line":922},7,[739,924,809],{"class":763},[739,926,927],{"class":745},"owner",[739,929,797],{"class":763},[739,931,800],{"class":763},[739,933,803],{"class":763},[739,935,937,940,942,944,946,948,950,952],{"class":741,"line":936},8,[739,938,939],{"class":763},"      \"",[739,941,812],{"class":888},[739,943,797],{"class":763},[739,945,800],{"class":763},[739,947,764],{"class":763},[739,949,821],{"class":749},[739,951,797],{"class":763},[739,953,826],{"class":763},[739,955,957,959,962,964,966,968,971,973],{"class":741,"line":956},9,[739,958,939],{"class":763},[739,960,961],{"class":888},"first_name",[739,963,797],{"class":763},[739,965,800],{"class":763},[739,967,764],{"class":763},[739,969,970],{"class":749},"Dana",[739,972,797],{"class":763},[739,974,826],{"class":763},[739,976,978,980,983,985,987,989,992,994],{"class":741,"line":977},10,[739,979,939],{"class":763},[739,981,982],{"class":888},"last_name",[739,984,797],{"class":763},[739,986,800],{"class":763},[739,988,764],{"class":763},[739,990,991],{"class":749},"Okafor",[739,993,797],{"class":763},[739,995,826],{"class":763},[739,997,999,1001,1004,1006,1008,1010,1013,1015],{"class":741,"line":998},11,[739,1000,939],{"class":763},[739,1002,1003],{"class":888},"email",[739,1005,797],{"class":763},[739,1007,800],{"class":763},[739,1009,764],{"class":763},[739,1011,1012],{"class":749},"dana@example.com",[739,1014,797],{"class":763},[739,1016,826],{"class":763},[739,1018,1020,1022,1025,1027,1029,1031,1034],{"class":741,"line":1019},12,[739,1021,939],{"class":763},[739,1023,1024],{"class":888},"role",[739,1026,797],{"class":763},[739,1028,800],{"class":763},[739,1030,764],{"class":763},[739,1032,1033],{"class":749},"ADMINISTRATOR",[739,1035,773],{"class":763},[739,1037,1039],{"class":741,"line":1038},13,[739,1040,1041],{"class":763},"    },\n",[739,1043,1045,1047,1050,1052,1054,1057,1059,1062,1064,1066,1068,1071,1073],{"class":741,"line":1044},14,[739,1046,809],{"class":763},[739,1048,1049],{"class":745},"scopes",[739,1051,797],{"class":763},[739,1053,800],{"class":763},[739,1055,1056],{"class":763}," [",[739,1058,797],{"class":763},[739,1060,1061],{"class":749},"organization:read",[739,1063,797],{"class":763},[739,1065,901],{"class":763},[739,1067,764],{"class":763},[739,1069,1070],{"class":749},"users:read",[739,1072,797],{"class":763},[739,1074,1075],{"class":763},"],\n",[739,1077,1079,1081,1084,1086,1088,1090,1093,1095],{"class":741,"line":1078},15,[739,1080,809],{"class":763},[739,1082,1083],{"class":745},"expires_at",[739,1085,797],{"class":763},[739,1087,800],{"class":763},[739,1089,764],{"class":763},[739,1091,1092],{"class":749},"2027-01-10T07:59:59.999Z",[739,1094,797],{"class":763},[739,1096,826],{"class":763},[739,1098,1100,1102,1105,1107,1109,1111,1114],{"class":741,"line":1099},16,[739,1101,809],{"class":763},[739,1103,1104],{"class":745},"created_at",[739,1106,797],{"class":763},[739,1108,800],{"class":763},[739,1110,764],{"class":763},[739,1112,1113],{"class":749},"2026-10-12T16:20:41.118Z",[739,1115,773],{"class":763},[739,1117,1119],{"class":741,"line":1118},17,[739,1120,1121],{"class":763},"  },\n",[739,1123,1125,1127,1130,1132,1134,1136,1138,1141,1143,1145,1147,1150,1152],{"class":741,"line":1124},18,[739,1126,790],{"class":763},[739,1128,1129],{"class":793},"meta",[739,1131,797],{"class":763},[739,1133,800],{"class":763},[739,1135,883],{"class":763},[739,1137,764],{"class":763},[739,1139,1140],{"class":745},"request_id",[739,1142,797],{"class":763},[739,1144,800],{"class":763},[739,1146,764],{"class":763},[739,1148,1149],{"class":749},"8f2c4b1e-...",[739,1151,797],{"class":763},[739,1153,1154],{"class":763}," }\n",[739,1156,1158],{"class":741,"line":1157},19,[739,1159,1160],{"class":763},"}\n",[553,1162,1163,1165,1166,1169],{},[721,1164,1049],{}," is the token's ",[572,1167,1168],{},"effective"," set for this request: what it was granted, limited by its owner's current role and by the endpoints available today.",[553,1171,1172,1173,1175],{},"Then read your organization's settings, which needs the ",[721,1174,1061],{}," scope:",[730,1177,1179],{"className":732,"code":1178,"language":734,"meta":735,"style":735},"curl https:\u002F\u002Fapp.bookyourpto.com\u002Fapi\u002Fv1\u002Forganization \\\n  -H \"Authorization: Bearer $BOOKYOURPTO_TOKEN\"\n",[721,1180,1181,1190],{"__ignoreMap":735},[739,1182,1183,1185,1188],{"class":741,"line":742},[739,1184,746],{"class":745},[739,1186,1187],{"class":749}," https:\u002F\u002Fapp.bookyourpto.com\u002Fapi\u002Fv1\u002Forganization",[739,1189,754],{"class":753},[739,1191,1192,1194,1196,1198,1200],{"class":741,"line":757},[739,1193,760],{"class":749},[739,1195,764],{"class":763},[739,1197,767],{"class":749},[739,1199,770],{"class":753},[739,1201,773],{"class":763},[557,1203,1205],{"id":1204},"_4-read-the-response","4. Read the response",[553,1207,1208],{},"Every response is JSON in the same envelope:",[562,1210,1211,1219,1235],{},[565,1212,1213,1214,1216,1217,599],{},"A successful response has ",[721,1215,794],{}," (an object or a list) and ",[721,1218,1129],{},[565,1220,1221,1222,1225,1226,1228,1229,1232,1233,599],{},"A failed response has ",[721,1223,1224],{},"error"," with a machine-readable ",[721,1227,721],{}," and a human-readable ",[721,1230,1231],{},"message",", plus ",[721,1234,1129],{},[565,1236,1237,1240,1241,1244],{},[721,1238,1239],{},"meta.request_id"," identifies the request. The same value is returned in the ",[721,1242,1243],{},"X-Request-Id"," header. Quote it when you contact support.",[730,1246,1248],{"className":776,"code":1247,"language":778,"meta":735,"style":735},"{\n  \"error\": {\n    \"code\": \"SCOPE_MISSING\",\n    \"message\": \"This token is missing the organization:read scope.\"\n  },\n  \"meta\": { \"request_id\": \"3a91d0c2-...\" }\n}\n",[721,1249,1250,1254,1266,1285,1302,1306,1335],{"__ignoreMap":735},[739,1251,1252],{"class":741,"line":742},[739,1253,785],{"class":763},[739,1255,1256,1258,1260,1262,1264],{"class":741,"line":757},[739,1257,790],{"class":763},[739,1259,1224],{"class":793},[739,1261,797],{"class":763},[739,1263,800],{"class":763},[739,1265,803],{"class":763},[739,1267,1268,1270,1272,1274,1276,1278,1281,1283],{"class":741,"line":806},[739,1269,809],{"class":763},[739,1271,721],{"class":745},[739,1273,797],{"class":763},[739,1275,800],{"class":763},[739,1277,764],{"class":763},[739,1279,1280],{"class":749},"SCOPE_MISSING",[739,1282,797],{"class":763},[739,1284,826],{"class":763},[739,1286,1287,1289,1291,1293,1295,1297,1300],{"class":741,"line":829},[739,1288,809],{"class":763},[739,1290,1231],{"class":745},[739,1292,797],{"class":763},[739,1294,800],{"class":763},[739,1296,764],{"class":763},[739,1298,1299],{"class":749},"This token is missing the organization:read scope.",[739,1301,773],{"class":763},[739,1303,1304],{"class":741,"line":850},[739,1305,1121],{"class":763},[739,1307,1308,1310,1312,1314,1316,1318,1320,1322,1324,1326,1328,1331,1333],{"class":741,"line":871},[739,1309,790],{"class":763},[739,1311,1129],{"class":793},[739,1313,797],{"class":763},[739,1315,800],{"class":763},[739,1317,883],{"class":763},[739,1319,764],{"class":763},[739,1321,1140],{"class":745},[739,1323,797],{"class":763},[739,1325,800],{"class":763},[739,1327,764],{"class":763},[739,1329,1330],{"class":749},"3a91d0c2-...",[739,1332,797],{"class":763},[739,1334,1154],{"class":763},[739,1336,1337],{"class":741,"line":922},[739,1338,1160],{"class":763},[553,1340,1341,1342,1345,1346,1348],{},"Branch on ",[721,1343,1344],{},"error.code",", never on the message text. The full list is on the ",[675,1347,175],{"href":176}," page.",[557,1350,1352],{"id":1351},"next-steps","Next steps",[562,1354,1355,1368,1377,1382,1388,1395],{},[565,1356,1357,1358,1360,1361,1360,1363,1365,1366,599],{},"Follow a guide for the area you are integrating: ",[675,1359,190],{"href":191},", ",[675,1362,195],{"href":196},[675,1364,200],{"href":201}," or ",[675,1367,205],{"href":206},[565,1369,1370,1371,1373,1374,599],{},"Browse every endpoint in the ",[675,1372,249],{"href":250},", or import the ",[675,1375,1376],{"href":240},"Postman collection",[565,1378,1379,1380,599],{},"Learn how lists are paginated in ",[675,1381,170],{"href":171},[565,1383,1384,1385,1387],{},"Plan for ",[675,1386,180],{"href":181}," before you run a bulk sync.",[565,1389,1390,1391,1394],{},"Subscribe to ",[675,1392,1393],{"href":216},"webhooks"," instead of polling for changes.",[565,1396,1397,1398,1400],{},"Set a reminder to ",[675,1399,705],{"href":704}," the token before it expires. The owner is also emailed seven days before expiry.",[1402,1403,1404],"style",{},"html pre.shiki code .sBMFI, html code.shiki .sBMFI{--shiki-light:#E2931D;--shiki-default:#FFCB6B;--shiki-dark:#FFCB6B}html pre.shiki code .sfazB, html code.shiki .sfazB{--shiki-light:#91B859;--shiki-default:#C3E88D;--shiki-dark:#C3E88D}html pre.shiki code .sTEyZ, html code.shiki .sTEyZ{--shiki-light:#90A4AE;--shiki-default:#EEFFFF;--shiki-dark:#BABED8}html pre.shiki code .sMK4o, html code.shiki .sMK4o{--shiki-light:#39ADB5;--shiki-default:#89DDFF;--shiki-dark:#89DDFF}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .spNyl, html code.shiki .spNyl{--shiki-light:#9C3EDA;--shiki-default:#C792EA;--shiki-dark:#C792EA}html pre.shiki code .sbssI, html code.shiki .sbssI{--shiki-light:#F76D47;--shiki-default:#F78C6C;--shiki-dark:#F78C6C}",{"title":735,"searchDepth":742,"depth":757,"links":1406},[1407,1408,1409,1410,1411,1412],{"id":559,"depth":757,"text":560},{"id":578,"depth":757,"text":579},{"id":631,"depth":757,"text":632},{"id":715,"depth":757,"text":716},{"id":1204,"depth":757,"text":1205},{"id":1351,"depth":757,"text":1352},"Switch the API on, create your first token in Settings > API, make a request with curl and read the response.","md",null,{},{"icon":159},{"title":5,"description":1413},"LavLUASLqzKEQFCIiJOVXEBC2eL7D4yFxyxreBmnC-M",[1421,1423],{"title":152,"path":153,"stem":154,"description":1422,"icon":155,"children":-1},"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.",{"title":161,"path":162,"stem":163,"description":1424,"icon":61,"children":-1},"How API tokens are formatted and sent, how expiry, rotation and revocation work, IP allowlists, what stops a token, and how to store one safely.",1791906527770]