{"openapi":"3.1.0","info":{"title":"HiBob (BYOK) API","version":"0.1.0","description":"HiBob (BYOK) lets an AI assistant read your own HiBob data through the HiBob API with a key you supply (service user ID). Read-only: 12 tools (search_employees, list_profiles, get_whos_out, get_out_today, list_time_off_changes, get_time_off_balance, list_policy_types, list_named_lists, list_employee_fields, list_onboarding_wizards, list_custom_tables, get_employee_work_history). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-hibob.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-hibob/docs"},"termsOfService":"https://connectorbay.com/byok-hibob/terms"},"servers":[{"url":"https://byok-hibob.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-hibob/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/search_employees":{"post":{"operationId":"search_employees","summary":"Search Bob employees: active ones by default, or including terminated and leave employees. Returns name, email, title, d","description":"Search Bob employees: active ones by default, or including terminated and leave employees. Returns name, email, title, department, site, start date and manager. Limited to what the service user may see. Use for \"Who works at the company according to Bob\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"show_inactive":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include terminated, hired and on-leave employees (the service user needs access to them).","title":"Show Inactive"},"human_readable":{"anyOf":[{"enum":["APPEND","REPLACE"],"type":"string"},{"type":"null"}],"default":null,"description":"APPEND adds readable values next to raw ones, REPLACE returns readable values only; leave out for raw values.","title":"Human Readable"}},"title":"search_employeesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_profiles":{"post":{"operationId":"list_profiles","summary":"List the public profile section of all active employees: name, email, title, department, site, start date and manager. U","description":"List the public profile section of all active employees: name, email, title, department, site, start date and manager. Use for \"Who is in the company directory\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_profilesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_whos_out":{"post":{"operationId":"get_whos_out","summary":"List who is out of office between two dates (approved time off by default) with employee, policy type, status and the da","description":"List who is out of office between two dates (approved time off by default) with employee, policy type, status and the dates or hours. Use for \"Who is out of office next week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date_from":{"description":"First day of the period (YYYY-MM-DD).","maxLength":10,"title":"Date From","type":"string"},"date_to":{"description":"Last day of the period (YYYY-MM-DD).","maxLength":10,"title":"Date To","type":"string"},"include_pending":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include requests that are still pending approval.","title":"Include Pending"},"include_hourly":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include hourly requests.","title":"Include Hourly"}},"required":["date_from","date_to"],"title":"get_whos_outArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_out_today":{"post":{"operationId":"get_out_today","summary":"List employees who are out of office today or on a given date with policy type and date range. Use for \"Who is off today","description":"List employees who are out of office today or on a given date with policy type and date range. Use for \"Who is off today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"today":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Date to report on (YYYY-MM-DD); default is today in UTC.","title":"Today"},"include_hourly":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include hourly requests.","title":"Include Hourly"},"site_id":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only employees of this site (numeric site id).","title":"Site Id"}},"title":"get_out_todayArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_time_off_changes":{"post":{"operationId":"list_time_off_changes","summary":"List time off requests created, canceled, deleted or set to pending since a date (at most six months back) with employee","description":"List time off requests created, canceled, deleted or set to pending since a date (at most six months back) with employee, policy type, dates, duration and cost. Use for \"Which time off requests changed in the last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"since":{"description":"Start of the range as an ISO 8601 date-time, at most six months ago, for example 2026-10-01T00:00:00Z.","maxLength":40,"title":"Since","type":"string"},"date_to":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the range as an ISO 8601 date-time, after since and at most six months later; default is now.","title":"Date To"},"include_pending":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include requests changed to pending.","title":"Include Pending"}},"required":["since"],"title":"list_time_off_changesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_time_off_balance":{"post":{"operationId":"get_time_off_balance","summary":"Show one employee's balance for a time off policy type on a date: balance, taken, allowance, adjustments and policy name","description":"Show one employee's balance for a time off policy type on a date: balance, taken, allowance, adjustments and policy name. Use for \"How many vacation days does employee 3332 have left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Employee id in Bob, from search_employees.","maxLength":60,"title":"Id","type":"string"},"policy_type":{"description":"Name of the policy type, as returned by list_policy_types, for example Holiday.","maxLength":100,"title":"Policy Type","type":"string"},"date":{"description":"Date for the balance (YYYY-MM-DD).","maxLength":10,"title":"Date","type":"string"}},"required":["id","policy_type","date"],"title":"get_time_off_balanceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_policy_types":{"post":{"operationId":"list_policy_types","summary":"List the names of the company's time off policy types (for example Holiday, Sick). Use for \"What time off policy types d","description":"List the names of the company's time off policy types (for example Holiday, Sick). Use for \"What time off policy types does Bob have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_policy_typesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_named_lists":{"post":{"operationId":"list_named_lists","summary":"List the company lists in Bob (departments, sites and other dropdown lists) with their items, ids and archived flags. Us","description":"List the company lists in Bob (departments, sites and other dropdown lists) with their items, ids and archived flags. Use for \"What are the department and site lists in Bob\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include_archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include archived list items.","title":"Include Archived"}},"title":"list_named_listsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_employee_fields":{"post":{"operationId":"list_employee_fields","summary":"List all employee fields defined in Bob with id, category, name, type and the list they use. Useful for knowing what dat","description":"List all employee fields defined in Bob with id, category, name, type and the list they use. Useful for knowing what data exists. Use for \"Which employee fields are defined in Bob\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_employee_fieldsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_onboarding_wizards":{"post":{"operationId":"list_onboarding_wizards","summary":"List the onboarding wizards defined in Bob with id and name. Use for \"Which onboarding wizards exist in Bob\".","description":"List the onboarding wizards defined in Bob with id and name. Use for \"Which onboarding wizards exist in Bob\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_onboarding_wizardsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_custom_tables":{"post":{"operationId":"list_custom_tables","summary":"List the custom employee tables in Bob with id, name, description and column names and types. Use for \"Which custom tabl","description":"List the custom employee tables in Bob with id, name, description and column names and types. Use for \"Which custom tables does Bob have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_custom_tablesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_employee_work_history":{"post":{"operationId":"get_employee_work_history","summary":"Show one employee's work history entries (effective dates, reports-to, title, department, site, change reason). Titles a","description":"Show one employee's work history entries (effective dates, reports-to, title, department, site, change reason). Titles and departments are list entry ids. Use for \"What is the work history of employee 3332\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Employee id in Bob, from search_employees.","maxLength":60,"title":"Id","type":"string"},"include_archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include archived columns.","title":"Include Archived"}},"required":["id"],"title":"get_employee_work_historyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}