{"info":{"title":"Bindle API","description":"Leave balances and time off for your company.\n\n## Authentication\n\nEvery endpoint except the leave calculator needs an API access token. If you are a\nBindle account owner or administrator you can find yours by logging into Bindle and\nlooking at the Admin page.\n\nSend it in a header:\n\n```\nAuthorization: Token token=your_access_token_goes_here\n```\n\nAn invalid or inactive token gets a `401`. A token only ever sees its own company.\n\n## Reporting on a period\n\n`GET /api/v1/leave` answers questions like \"what was everyone's annual leave balance\nat the end of each quarter, and how much did they book or take inside it\". Ask for the\nperiod you care about and total it up however you like. Bindle does not impose a\nquarter, a month or a leave year on the figures.\n\nA booking that straddles the edge of the period is counted only for the part that\nfalls inside it, so consecutive periods never double count the same day.\n\nLeaving `from` out measures each entitlement from the day it started in Bindle, which\nis how you ask \"everything so far\" without knowing when anyone joined.\n\nBalances are in days. `null` means the entitlement does not carry a balance, or your\ncompany is not set up to track balances.\n","contact":{"email":"support@bindle.io"},"version":"1.0.0"},"swagger":"2.0","produces":["application/json"],"securityDefinitions":{"access_token":{"type":"apiKey","name":"Authorization","in":"header","description":"Send your access token as: Token token=your_access_token_goes_here"}},"security":[{"access_token":[]}],"host":"app.bindle.io","tags":[{"name":"leave","description":"Balances and time off over a period, for every entitlement a person has."},{"name":"balance","description":"The main entitlement balance as at today."},{"name":"entitlements","description":"Which entitlements a person has."},{"name":"calculator","description":"Ad hoc accrual maths. No account or token needed."},{"name":"ping","description":"Check an access token works."}],"paths":{"/api/v1/balance":{"get":{"summary":"The main entitlement balance as at today","description":"The balance in days for the person's main entitlement, as at today.\n\nFor a balance as at another date, for every entitlement rather than just the main\none, or for the leave taken inside a period, use the leave endpoint.\n","produces":["application/json"],"parameters":[{"in":"query","name":"email","description":"The email address of the person.","type":"string","required":true}],"responses":{"200":{"description":"The balance in days","schema":{"$ref":"#/definitions/Balance"},"examples":{"application/json":{"balance":"35.5"}}},"400":{"description":"The company does not track balances, or the main entitlement carries none","schema":{"$ref":"#/definitions/Error"},"examples":{"application/json":{"error":"Your company is not set up to use Bindle to track balances."}}},"401":{"description":"The access token is missing, invalid or inactive","schema":{"$ref":"#/definitions/Error"},"examples":{"application/json":{"error":"Unauthorized. Invalid or inactive API access token."}}},"404":{"description":"No person in your company has that email address","schema":{"$ref":"#/definitions/Error"},"examples":{"application/json":{"error":"Not found. Main entitlement not found for that email address."}}}},"tags":["balance"],"operationId":"getBalance"}},"/api/v1/entitlements":{"get":{"summary":"The names of every entitlement a person has","description":"Names only. For balances and leave taken, use the leave endpoint.","produces":["application/json"],"parameters":[{"in":"query","name":"email","description":"The email address of the person.","type":"string","required":true}],"responses":{"200":{"description":"The entitlement names","schema":{"$ref":"#/definitions/EntitlementNames"},"examples":{"application/json":{"entitlements":["Annual Leave","Personal Leave","Compassionate Leave"]}}},"401":{"description":"The access token is missing, invalid or inactive","schema":{"$ref":"#/definitions/Error"},"examples":{"application/json":{"error":"Unauthorized. Invalid or inactive API access token."}}},"404":{"description":"No person in your company has that email address, or they have no entitlements","schema":{"$ref":"#/definitions/Error"},"examples":{"application/json":{"error":"No entitlements found for that email address."}}}},"tags":["entitlements"],"operationId":"getEntitlements"}},"/api/v1/leave":{"get":{"summary":"Every entitlement, with its balance at the end of a period and the leave inside it","description":"Returns every entitlement the person has, not just their main one.\n\n`balance` is in days, as at `to`, and is `null` where the entitlement carries no\nbalance or the company does not track balances. The rest of the response is still\nreturned.\n\n`from` may be left out, in which case each entitlement is measured from the day it\nstarted in Bindle and says so in its own `from`. The `from` at the top level echoes\nwhat you asked for, and is null when you asked for nothing.\n\n`as_at` is the day you are reporting as at, and defaults to today. It decides only\nwhere `taken` stops and `booked` starts, never the total. Pass a past date to see a\nperiod as it stood then rather than as it stands now, which is how you reproduce a\nreport without having run it on the day.\n\n`balance` is a different date on purpose: it is always as at `to`, the end of the\nperiod you asked about, so `to` at a quarter end gives the balance at that quarter\nend whatever `as_at` says.\n\n`leave` is the leave booked or taken between `from` and `to` inclusive, in days.\n`days` is the total. The other six figures are three independent ways of splitting\nthat same total, so each pair adds back up to it:\n\n* `taken` and `booked`, either side of `as_at`\n* `paid` and `unpaid`\n* `approved` and `pending`\n\nRejected and cancelled bookings are counted nowhere. A booking that straddles the\nedge of the period counts only for the part inside it, so consecutive periods never\ndouble count a day.\n","produces":["application/json"],"parameters":[{"in":"query","name":"email","description":"The email address of the person.","type":"string","required":true},{"in":"query","name":"from","description":"First day of the period, as YYYY-MM-DD. Inclusive. Defaults to the day each entitlement started in Bindle.","type":"string","format":"date","required":false},{"in":"query","name":"to","description":"Last day of the period, as YYYY-MM-DD. Inclusive. Balances are as at this date.","type":"string","format":"date","required":true},{"in":"query","name":"as_at","description":"The day to report as at, as YYYY-MM-DD. Splits leave into taken and booked. Defaults to today.","type":"string","format":"date","required":false}],"responses":{"200":{"description":"Entitlements, balances and leave for the period","schema":{"$ref":"#/definitions/PersonLeave"},"examples":{"application/json":{"email":"someone@your-company.com","from":"2026-01-01","to":"2026-03-31","as_at":"2026-02-14","entitlements":[{"from":"2026-01-01","name":"Annual Leave","balance":"12.8151","leave":{"days":5.0,"taken":3.0,"booked":2.0,"paid":5.0,"unpaid":0,"approved":4.0,"pending":1.0}},{"from":"2024-07-01","name":"Compassionate Leave","balance":null,"leave":{"days":0,"taken":0,"booked":0,"paid":0,"unpaid":0,"approved":0,"pending":0}}]}}},"400":{"description":"The period runs backwards, or a parameter is missing or unparseable","schema":{"$ref":"#/definitions/Error"},"examples":{"application/json":{"error":"from must not be later than to."}}},"401":{"description":"The access token is missing, invalid or inactive","schema":{"$ref":"#/definitions/Error"},"examples":{"application/json":{"error":"Unauthorized. Invalid or inactive API access token."}}},"404":{"description":"No person in your company has that email address","schema":{"$ref":"#/definitions/Error"},"examples":{"application/json":{"error":"Not found. No person with that email address."}}}},"tags":["leave"],"operationId":"getLeave"}},"/api/v1/calculator":{"post":{"summary":"Calculate a balance without an account","description":"Open to anyone. No access token needed. Assumes New South Wales.","produces":["application/json"],"consumes":["application/json"],"parameters":[{"name":"postCalculator","in":"body","required":true,"schema":{"$ref":"#/definitions/postCalculator"}}],"responses":{"201":{"description":"The calculated balance in days","schema":{"$ref":"#/definitions/CalculatedBalance"},"examples":{"application/json":{"balance":12.3}}},"400":{"description":"The calculation is not valid. The body is a map of field name to the problems with it, for example {\"start_date\": [\"is missing\"]}.","schema":{"type":"object"}}},"tags":["calculator"],"operationId":"postCalculator"}},"/api/v1/ping":{"get":{"summary":"Check an access token works","description":"Returns pong when the access token is valid and the subscription is active.","produces":["application/json"],"responses":{"200":{"description":"The token is good","schema":{"$ref":"#/definitions/Pong"},"examples":{"application/json":{"message":"pong"}}},"401":{"description":"The access token is missing, invalid or inactive","schema":{"$ref":"#/definitions/Error"},"examples":{"application/json":{"error":"Unauthorized. Invalid or inactive API access token."}}}},"tags":["ping"],"operationId":"getPing"}}},"definitions":{"Balance":{"type":"object","properties":{"balance":{"type":"string","description":"The main entitlement balance in days, as at today."}},"required":["balance"],"description":"Balance model"},"Error":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Error model"},"EntitlementNames":{"type":"object","properties":{"entitlements":{"type":"array","items":{"type":"string"},"description":"The name of every entitlement the person has."}},"required":["entitlements"],"description":"EntitlementNames model"},"PersonLeave":{"type":"object","properties":{"email":{"type":"string","description":"The email address that was asked for."},"from":{"type":"string","description":"First day of the period, as YYYY-MM-DD."},"to":{"type":"string","description":"Last day of the period, as YYYY-MM-DD."},"as_at":{"type":"string","description":"Today, as YYYY-MM-DD. The boundary between taken and booked."},"entitlements":{"type":"array","items":{"$ref":"#/definitions/EntitlementLeave"},"description":"Every entitlement the person has, not just their main one."}},"required":["email","from","to","as_at","entitlements"],"description":"PersonLeave model"},"EntitlementLeave":{"type":"object","properties":{"from":{"type":"string","description":"The day this entitlement was measured from, as YYYY-MM-DD. The from you asked for, or the day the entitlement started in Bindle when you did not."},"name":{"type":"string","description":"The name of the entitlement, for example Annual Leave."},"balance":{"type":"string","description":"Balance in days as at the end of the period. Null where the entitlement carries no balance, or the company does not track balances."},"leave":{"allOf":[{"$ref":"#/definitions/LeaveFigure"}],"description":"Leave booked or taken inside the period, totalled and split three ways."}},"required":["from","name","balance","leave"]},"LeaveFigure":{"type":"object","properties":{"days":{"type":"number","description":"Total days booked or taken inside the period. The six figures below are three independent splits of this number."},"taken":{"type":"number","description":"Days on or before as_at. With booked, adds up to days."},"booked":{"type":"number","description":"Days after as_at. With taken, adds up to days."},"paid":{"type":"number","description":"Days of paid leave. With unpaid, adds up to days."},"unpaid":{"type":"number","description":"Days of unpaid leave. With paid, adds up to days."},"approved":{"type":"number","description":"Days already approved. With pending, adds up to days."},"pending":{"type":"number","description":"Days requested but not yet approved. With approved, adds up to days."}},"required":["days","taken","booked","paid","unpaid","approved","pending"]},"postCalculator":{"type":"object","properties":{"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"accrual_rate":{"type":"number","format":"double"},"part_time":{"type":"boolean"},"part_time_hours":{"type":"number","format":"double"},"shift_worker":{"type":"boolean","default":false},"days_taken":{"type":"number","format":"double"}},"required":["start_date","end_date","days_taken"],"description":"Calculate a balance without an account"},"CalculatedBalance":{"type":"object","properties":{"balance":{"type":"number","description":"The calculated balance in days."}},"required":["balance"],"description":"CalculatedBalance model"},"Pong":{"type":"object","properties":{"message":{"type":"string","description":"Always pong."}},"required":["message"],"description":"Pong model"}}}