{"openapi":"3.1.0","info":{"title":"Badger HR API","version":"1.0.0","termsOfService":"https://badgerhr.com/trust/terms","description":"Read and update your Badger HR data.\n\nAuthenticate with an account API key, created by an admin under\nSettings > API Keys, and sent as a bearer token:\n\n    Authorization: Bearer bhr_xxxxxxxx\n\nEach key carries per-area permissions. `write` implies `read`. An unknown\nor revoked key gets 401; a valid key without the required grant gets 403.\n\nEvery request is scoped to the key's account. A record belonging to\nanother account is reported as 404, never 403."},"servers":[{"url":"https://badgerhr.com","description":"Badger HR"}],"security":[{"ApiKey":[]}],"tags":[{"name":"VendorAccesses","description":"VendorAccess records."},{"name":"Vendors","description":"Vendor records."}],"paths":{"/api/v1/vendors":{"get":{"operationId":"listVendors","summary":"List vendors","tags":["Vendors"],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["vendors"],"properties":{"vendors":{"type":"array","items":{"$ref":"#/components/schemas/Vendor"}}}}}}},"401":{"description":"The API key is missing, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the required permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-permission":"vendors:read","description":"Returns the account's vendors, ordered by name. Archived vendors are excluded unless asked for.\n\nRequires the `vendors: read` permission.","parameters":[{"name":"status","in":"query","required":false,"description":"Only vendors with this status.","schema":{"type":"string","enum":["active","under_review","approved","inactive"]}},{"name":"category","in":"query","required":false,"description":"Only vendors in this category.","schema":{"type":"string","enum":["cloud_infrastructure","saas","payroll","benefits","recruitment","analytics","security","professional_services","other"]}},{"name":"include_archived","in":"query","required":false,"description":"Set to true to include archived vendors.","schema":{"type":"boolean"}}]},"post":{"operationId":"createVendor","summary":"Create a vendor","tags":["Vendors"],"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["vendor"],"properties":{"vendor":{"$ref":"#/components/schemas/Vendor"}}}}}},"401":{"description":"The API key is missing, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the required permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The record could not be saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"x-required-permission":"vendors:write","description":"The new vendor is attributed to the admin who created the API key.\n\nRequires the `vendors: write` permission.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VendorCreateRequest"}}}}}},"/api/v1/vendors/{id}":{"get":{"operationId":"getVendor","summary":"Get a vendor","tags":["Vendors"],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["vendor"],"properties":{"vendor":{"$ref":"#/components/schemas/Vendor"}}}}}},"401":{"description":"The API key is missing, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the required permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-permission":"vendors:read","description":"Requires the `vendors: read` permission.","parameters":[{"name":"id","in":"path","required":true,"description":"Identifier of the record.","schema":{"type":"integer"}}]},"patch":{"operationId":"updateVendor","summary":"Update a vendor","tags":["Vendors"],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["vendor"],"properties":{"vendor":{"$ref":"#/components/schemas/Vendor"}}}}}},"401":{"description":"The API key is missing, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the required permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The record could not be saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"x-required-permission":"vendors:write","description":"Partial updates are fine — send only the attributes you are changing.\n\nRequires the `vendors: write` permission.","parameters":[{"name":"id","in":"path","required":true,"description":"Identifier of the record.","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VendorUpdateRequest"}}}}}},"/api/v1/vendors/{id}/archive":{"post":{"operationId":"archiveVendor","summary":"Archive a vendor","tags":["Vendors"],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["vendor"],"properties":{"vendor":{"$ref":"#/components/schemas/Vendor"}}}}}},"401":{"description":"The API key is missing, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the required permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-permission":"vendors:write","description":"Idempotent: archiving an already archived vendor changes nothing.\n\nRequires the `vendors: write` permission.","parameters":[{"name":"id","in":"path","required":true,"description":"Identifier of the record.","schema":{"type":"integer"}}]}},"/api/v1/vendors/{id}/restore":{"post":{"operationId":"restoreVendor","summary":"Restore an archived vendor","tags":["Vendors"],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["vendor"],"properties":{"vendor":{"$ref":"#/components/schemas/Vendor"}}}}}},"401":{"description":"The API key is missing, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the required permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-permission":"vendors:write","description":"Idempotent: restoring an active vendor changes nothing.\n\nRequires the `vendors: write` permission.","parameters":[{"name":"id","in":"path","required":true,"description":"Identifier of the record.","schema":{"type":"integer"}}]}},"/api/v1/vendors/{vendor_id}/accesses":{"get":{"operationId":"listVendorAccesses","summary":"List who has access to a vendor","tags":["VendorAccesses"],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["vendor_accesses"],"properties":{"vendor_accesses":{"type":"array","items":{"$ref":"#/components/schemas/VendorAccess"}}}}}}},"401":{"description":"The API key is missing, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the required permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-permission":"vendors:read","description":"Revoked access is excluded unless asked for.\n\nRequires the `vendors: read` permission.","parameters":[{"name":"vendor_id","in":"path","required":true,"description":"Identifier of the record.","schema":{"type":"integer"}},{"name":"include_revoked","in":"query","required":false,"description":"Set to true to include revoked access.","schema":{"type":"boolean"}},{"name":"access_level","in":"query","required":false,"description":"Only access at this level.","schema":{"type":"string","enum":["owner","admin","billing","standard","read_only"]}}]},"post":{"operationId":"createVendorAccess","summary":"Grant access to a vendor","tags":["VendorAccesses"],"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["vendor_access"],"properties":{"vendor_access":{"$ref":"#/components/schemas/VendorAccess"}}}}}},"401":{"description":"The API key is missing, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the required permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The record could not be saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"x-required-permission":"vendors:write","description":"Send either user_id (an employee) or external_contact_id (an outside party such as an accountant), not both.\n\nRequires the `vendors: write` permission.","parameters":[{"name":"vendor_id","in":"path","required":true,"description":"Identifier of the record.","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VendorAccessCreateRequest"}}}}}},"/api/v1/vendors/{vendor_id}/accesses/{id}":{"patch":{"operationId":"updateVendorAccess","summary":"Change an access level or its notes","tags":["VendorAccesses"],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["vendor_access"],"properties":{"vendor_access":{"$ref":"#/components/schemas/VendorAccess"}}}}}},"401":{"description":"The API key is missing, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the required permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The record could not be saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"x-required-permission":"vendors:write","description":"The person holding the access cannot be changed — revoke and grant instead.\n\nRequires the `vendors: write` permission.","parameters":[{"name":"vendor_id","in":"path","required":true,"description":"Identifier of the record.","schema":{"type":"integer"}},{"name":"id","in":"path","required":true,"description":"Identifier of the record.","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VendorAccessUpdateRequest"}}}}}},"/api/v1/vendors/{vendor_id}/accesses/{id}/revoke":{"post":{"operationId":"revokeVendorAccess","summary":"Revoke access","tags":["VendorAccesses"],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["vendor_access"],"properties":{"vendor_access":{"$ref":"#/components/schemas/VendorAccess"}}}}}},"401":{"description":"The API key is missing, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the required permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-permission":"vendors:write","description":"A soft revoke: the record is kept so the history of who had access remains auditable.\n\nRequires the `vendors: write` permission.","parameters":[{"name":"vendor_id","in":"path","required":true,"description":"Identifier of the record.","schema":{"type":"integer"}},{"name":"id","in":"path","required":true,"description":"Identifier of the record.","schema":{"type":"integer"}}]}}},"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","description":"An account API key, e.g. `bhr_xxxxxxxx`."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"ValidationError":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"string"}}}},"Vendor":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"name":{"type":"string","maxLength":100},"category":{"type":"string","enum":["cloud_infrastructure","saas","payroll","benefits","recruitment","analytics","security","professional_services","other"]},"description":{"type":["string","null"],"maxLength":1000},"website":{"type":["string","null"],"maxLength":500,"format":"uri"},"status":{"type":"string","enum":["active","under_review","approved","inactive"]},"contains_personal_data":{"type":"boolean"},"data_subjects":{"type":["string","null"]},"type_of_data":{"type":["string","null"]},"location_of_processing":{"type":["string","null"]},"international_transfers":{"type":"boolean"},"transfer_safeguards":{"type":["string","null"]},"processing_subcontracted":{"type":"boolean"},"subprocessor_list_url":{"type":["string","null"],"maxLength":500,"format":"uri"},"dpa_status":{"type":"string","enum":["not_required","not_started","in_progress","signed","expired"]},"dpa_signed_date":{"type":["string","null"],"format":"date"},"risk_level":{"type":["string","null"],"enum":["low","medium","high",null]},"review_date":{"type":["string","null"],"format":"date"},"notes":{"type":["string","null"],"maxLength":2000},"archived":{"type":"boolean","readOnly":true},"archived_at":{"type":["string","null"],"format":"date-time","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}}},"VendorAccess":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"compliance_vendor_id":{"type":"integer","readOnly":true},"access_level":{"type":"string","enum":["owner","admin","billing","standard","read_only"]},"holder_type":{"type":"string","readOnly":true},"holder_name":{"type":"string","readOnly":true},"holder_email":{"type":"string","readOnly":true},"holder_organisation":{"type":"string","readOnly":true},"user_id":{"type":["integer","null"]},"external_contact_id":{"type":["integer","null"]},"granted_on":{"type":["string","null"],"format":"date"},"notes":{"type":["string","null"],"maxLength":1000},"active":{"type":"boolean","readOnly":true},"revoked_at":{"type":["string","null"],"format":"date-time","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}}},"VendorAccessCreateRequest":{"type":"object","required":["vendor_access"],"properties":{"vendor_access":{"type":"object","properties":{"user_id":{"type":["integer","null"]},"external_contact_id":{"type":["integer","null"]},"access_level":{"type":"string","enum":["owner","admin","billing","standard","read_only"]},"granted_on":{"type":["string","null"],"format":"date"},"notes":{"type":["string","null"],"maxLength":1000}},"required":["access_level"]}}},"VendorAccessUpdateRequest":{"type":"object","required":["vendor_access"],"properties":{"vendor_access":{"type":"object","properties":{"user_id":{"type":["integer","null"]},"external_contact_id":{"type":["integer","null"]},"access_level":{"type":"string","enum":["owner","admin","billing","standard","read_only"]},"granted_on":{"type":["string","null"],"format":"date"},"notes":{"type":["string","null"],"maxLength":1000}}}}},"VendorCreateRequest":{"type":"object","required":["compliance_vendor"],"properties":{"compliance_vendor":{"type":"object","properties":{"name":{"type":"string","maxLength":100},"category":{"type":"string","enum":["cloud_infrastructure","saas","payroll","benefits","recruitment","analytics","security","professional_services","other"]},"description":{"type":["string","null"],"maxLength":1000},"website":{"type":["string","null"],"maxLength":500,"format":"uri"},"status":{"type":"string","enum":["active","under_review","approved","inactive"]},"contains_personal_data":{"type":"boolean"},"data_subjects":{"type":["string","null"]},"type_of_data":{"type":["string","null"]},"location_of_processing":{"type":["string","null"]},"international_transfers":{"type":"boolean"},"transfer_safeguards":{"type":["string","null"]},"processing_subcontracted":{"type":"boolean"},"subprocessor_list_url":{"type":["string","null"],"maxLength":500,"format":"uri"},"dpa_status":{"type":"string","enum":["not_required","not_started","in_progress","signed","expired"]},"dpa_signed_date":{"type":["string","null"],"format":"date"},"risk_level":{"type":["string","null"],"enum":["low","medium","high",null]},"review_date":{"type":["string","null"],"format":"date"},"notes":{"type":["string","null"],"maxLength":2000}},"required":["name","category"]}}},"VendorUpdateRequest":{"type":"object","required":["compliance_vendor"],"properties":{"compliance_vendor":{"type":"object","properties":{"name":{"type":"string","maxLength":100},"category":{"type":"string","enum":["cloud_infrastructure","saas","payroll","benefits","recruitment","analytics","security","professional_services","other"]},"description":{"type":["string","null"],"maxLength":1000},"website":{"type":["string","null"],"maxLength":500,"format":"uri"},"status":{"type":"string","enum":["active","under_review","approved","inactive"]},"contains_personal_data":{"type":"boolean"},"data_subjects":{"type":["string","null"]},"type_of_data":{"type":["string","null"]},"location_of_processing":{"type":["string","null"]},"international_transfers":{"type":"boolean"},"transfer_safeguards":{"type":["string","null"]},"processing_subcontracted":{"type":"boolean"},"subprocessor_list_url":{"type":["string","null"],"maxLength":500,"format":"uri"},"dpa_status":{"type":"string","enum":["not_required","not_started","in_progress","signed","expired"]},"dpa_signed_date":{"type":["string","null"],"format":"date"},"risk_level":{"type":["string","null"],"enum":["low","medium","high",null]},"review_date":{"type":["string","null"],"format":"date"},"notes":{"type":["string","null"],"maxLength":2000}}}}}}}}