Badger HR API
Version 1.0.0
Read and update your Badger HR data.
Authenticate with an account API key, created by an admin under Settings > API Keys, and sent as a bearer token:
Authorization: Bearer bhr_xxxxxxxx
Each key carries per-area permissions. write implies read. An unknown
or revoked key gets 401; a valid key without the required grant gets 403.
Every request is scoped to the key's account. A record belonging to another account is reported as 404, never 403.
Base URL
https://badgerhr.com
VendorAccesses
VendorAccess records.
get
/api/v1/vendors/{vendor_id}/accesses
vendors:read
List who has access to a vendor
Revoked access is excluded unless asked for.
Requires the vendors: read permission.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| vendor_id * | path | integer | Identifier of the record. |
| include_revoked | query | boolean | Set to true to include revoked access. |
| access_level | query | string | Only access at this level. one of: owner, admin, billing, standard, read_only |
Responses
-
200Success. -
401The API key is missing, unknown or revoked. -
403The API key lacks the required permission.
post
/api/v1/vendors/{vendor_id}/accesses
vendors:write
Grant access to a vendor
Send either userid (an employee) or externalcontact_id (an outside party such as an accountant), not both.
Requires the vendors: write permission.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| vendor_id * | path | integer | Identifier of the record. |
Request body
— nested under vendor_access
| Field | Type | Notes |
|---|---|---|
| user_id | integer or null | |
| external_contact_id | integer or null | |
| access_level * | string | one of: owner, admin, billing, standard, read_only |
| granted_on | string or null (date) | |
| notes | string or null | max 1000 characters |
* required
Responses
-
201Created. -
401The API key is missing, unknown or revoked. -
403The API key lacks the required permission. -
422The record could not be saved.
patch
/api/v1/vendors/{vendor_id}/accesses/{id}
vendors:write
Change an access level or its notes
The person holding the access cannot be changed — revoke and grant instead.
Requires the vendors: write permission.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| vendor_id * | path | integer | Identifier of the record. |
| id * | path | integer | Identifier of the record. |
Request body
— nested under vendor_access
| Field | Type | Notes |
|---|---|---|
| user_id | integer or null | |
| external_contact_id | integer or null | |
| access_level | string | one of: owner, admin, billing, standard, read_only |
| granted_on | string or null (date) | |
| notes | string or null | max 1000 characters |
* required
Responses
-
200Success. -
401The API key is missing, unknown or revoked. -
403The API key lacks the required permission. -
404No such record in this account. -
422The record could not be saved.
post
/api/v1/vendors/{vendor_id}/accesses/{id}/revoke
vendors:write
Revoke access
A soft revoke: the record is kept so the history of who had access remains auditable.
Requires the vendors: write permission.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| vendor_id * | path | integer | Identifier of the record. |
| id * | path | integer | Identifier of the record. |
Responses
-
200Success. -
401The API key is missing, unknown or revoked. -
403The API key lacks the required permission. -
404No such record in this account.
Vendors
Vendor records.
get
/api/v1/vendors
vendors:read
List vendors
Returns the account's vendors, ordered by name. Archived vendors are excluded unless asked for.
Requires the vendors: read permission.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| status | query | string | Only vendors with this status. one of: active, under_review, approved, inactive |
| category | query | string | Only vendors in this category. one of: cloud_infrastructure, saas, payroll, benefits, recruitment, analytics, security, professional_services, other |
| include_archived | query | boolean | Set to true to include archived vendors. |
Responses
-
200Success. -
401The API key is missing, unknown or revoked. -
403The API key lacks the required permission.
post
/api/v1/vendors
vendors:write
Create a vendor
The new vendor is attributed to the admin who created the API key.
Requires the vendors: write permission.
Request body
— nested under compliance_vendor
| Field | Type | Notes |
|---|---|---|
| name * | string | max 100 characters |
| category * | string | one of: cloud_infrastructure, saas, payroll, benefits, recruitment, analytics, security, professional_services, other |
| description | string or null | max 1000 characters |
| website | string or null (uri) | max 500 characters |
| status | string | one of: active, under_review, approved, inactive |
| contains_personal_data | boolean | |
| data_subjects | string or null | |
| type_of_data | string or null | |
| location_of_processing | string or null | |
| international_transfers | boolean | |
| transfer_safeguards | string or null | |
| processing_subcontracted | boolean | |
| subprocessor_list_url | string or null (uri) | max 500 characters |
| dpa_status | string | one of: not_required, not_started, in_progress, signed, expired |
| dpa_signed_date | string or null (date) | |
| risk_level | string or null | one of: low, medium, high, null |
| review_date | string or null (date) | |
| notes | string or null | max 2000 characters |
* required
Responses
-
201Created. -
401The API key is missing, unknown or revoked. -
403The API key lacks the required permission. -
422The record could not be saved.
get
/api/v1/vendors/{id}
vendors:read
Get a vendor
Requires the vendors: read permission.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| id * | path | integer | Identifier of the record. |
Responses
-
200Success. -
401The API key is missing, unknown or revoked. -
403The API key lacks the required permission. -
404No such record in this account.
patch
/api/v1/vendors/{id}
vendors:write
Update a vendor
Partial updates are fine — send only the attributes you are changing.
Requires the vendors: write permission.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| id * | path | integer | Identifier of the record. |
Request body
— nested under compliance_vendor
| Field | Type | Notes |
|---|---|---|
| name | string | max 100 characters |
| category | string | one of: cloud_infrastructure, saas, payroll, benefits, recruitment, analytics, security, professional_services, other |
| description | string or null | max 1000 characters |
| website | string or null (uri) | max 500 characters |
| status | string | one of: active, under_review, approved, inactive |
| contains_personal_data | boolean | |
| data_subjects | string or null | |
| type_of_data | string or null | |
| location_of_processing | string or null | |
| international_transfers | boolean | |
| transfer_safeguards | string or null | |
| processing_subcontracted | boolean | |
| subprocessor_list_url | string or null (uri) | max 500 characters |
| dpa_status | string | one of: not_required, not_started, in_progress, signed, expired |
| dpa_signed_date | string or null (date) | |
| risk_level | string or null | one of: low, medium, high, null |
| review_date | string or null (date) | |
| notes | string or null | max 2000 characters |
* required
Responses
-
200Success. -
401The API key is missing, unknown or revoked. -
403The API key lacks the required permission. -
404No such record in this account. -
422The record could not be saved.
post
/api/v1/vendors/{id}/archive
vendors:write
Archive a vendor
Idempotent: archiving an already archived vendor changes nothing.
Requires the vendors: write permission.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| id * | path | integer | Identifier of the record. |
Responses
-
200Success. -
401The API key is missing, unknown or revoked. -
403The API key lacks the required permission. -
404No such record in this account.
post
/api/v1/vendors/{id}/restore
vendors:write
Restore an archived vendor
Idempotent: restoring an active vendor changes nothing.
Requires the vendors: write permission.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| id * | path | integer | Identifier of the record. |
Responses
-
200Success. -
401The API key is missing, unknown or revoked. -
403The API key lacks the required permission. -
404No such record in this account.
Schemas
Error
| Field | Type | Notes |
|---|---|---|
| error | string |
ValidationError
| Field | Type | Notes |
|---|---|---|
| errors | array |
Vendor
| Field | Type | Notes |
|---|---|---|
| id | integer | read-only |
| name | string | max 100 characters |
| category | string | one of: cloud_infrastructure, saas, payroll, benefits, recruitment, analytics, security, professional_services, other |
| description | string or null | max 1000 characters |
| website | string or null (uri) | max 500 characters |
| status | string | one of: active, under_review, approved, inactive |
| contains_personal_data | boolean | |
| data_subjects | string or null | |
| type_of_data | string or null | |
| location_of_processing | string or null | |
| international_transfers | boolean | |
| transfer_safeguards | string or null | |
| processing_subcontracted | boolean | |
| subprocessor_list_url | string or null (uri) | max 500 characters |
| dpa_status | string | one of: not_required, not_started, in_progress, signed, expired |
| dpa_signed_date | string or null (date) | |
| risk_level | string or null | one of: low, medium, high, null |
| review_date | string or null (date) | |
| notes | string or null | max 2000 characters |
| archived | boolean | read-only |
| archived_at | string or null (date-time) | read-only |
| created_at | string (date-time) | read-only |
| updated_at | string (date-time) | read-only |
VendorAccess
| Field | Type | Notes |
|---|---|---|
| id | integer | read-only |
| compliance_vendor_id | integer | read-only |
| access_level | string | one of: owner, admin, billing, standard, read_only |
| holder_type | string | read-only |
| holder_name | string | read-only |
| holder_email | string | read-only |
| holder_organisation | string | read-only |
| user_id | integer or null | |
| external_contact_id | integer or null | |
| granted_on | string or null (date) | |
| notes | string or null | max 1000 characters |
| active | boolean | read-only |
| revoked_at | string or null (date-time) | read-only |
| created_at | string (date-time) | read-only |
| updated_at | string (date-time) | read-only |