SiberMate API Reference.

GET /health

Check API availability.

Returns a lightweight status response that can be used by uptime checks and deployment monitors.

GET /openapi.json

Retrieve the OpenAPI document.

Returns this OpenAPI document for tooling, SDK generation, and documentation workflows.

GET /ready

Check deployment readiness.

Returns whether the API is configured for serving traffic. This check does not validate tenant API keys, organization data access, or external service connectivity.

GET /company

Retrieve organization profile.

Returns the organization that owns the authenticated API key, including plan and trial state. This endpoint never describes another organization: passing companyId returns 400. MSP and Distributor keys should use GET /companies, which lists each child tenant with its own plan. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

GET /company/features

Retrieve enabled SiberMate modules.

Returns the enabled SiberMate modules for the organization that owns the authenticated API key. Passing companyId returns 400; use GET /companies to enumerate child tenants. This endpoint returns data for the organization associated with the authenticated API key.

GET /admins

List admin users.

Returns admin users (platform administrators) for the organization, with each admin's roles. Admin users are separate from learners: they administer SiberMate rather than take training. MSP and Distributor keys can pass companyId to read a child tenant's admins. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

POST /admins

Create an admin user and send an invite email.

Creates an admin user and sends them an invite email; the person completes setup from that email. Pass roles to limit what the admin can do (for example ["globalReadOnly"]). Without roles the admin receives full platform administrator access (globalAdmin) — call this only from trusted server-side systems. MSP and Distributor keys cannot create admins in a child tenant; use that tenant's own API key. This endpoint changes organization data and requires an authorized bearer token.

Request body

DELETE /admins/{adminId}

Delete an admin user.

Permanently removes an admin user's access to the organization. This endpoint changes organization data and should be called only from trusted server-side systems.

Parameters

PATCH /admins/{adminId}

Update an admin user.

Updates an admin user's profile. Pass roles to replace the admin's roles; omit it to leave them unchanged. This endpoint changes organization data and requires an authorized bearer token.

Parameters

Request body

POST /admins/{adminId}/resend-invite

Resend an admin user invite email.

Resends the invite email to an admin user who has not completed setup yet. This endpoint changes organization data and requires an authorized bearer token.

Parameters

DELETE /admins/bulk

Delete admin users in bulk.

Permanently removes several admin users in one call. This endpoint changes organization data and should be called only from trusted server-side systems.

Request body

GET /companies

List child tenant companies (MSP/Distributor only).

Returns the child tenant companies managed by the authenticated MSP or Distributor account, including each tenant's plan and trial state. Non-MSP API keys receive 403. Use the returned company id as the companyId query parameter on other read endpoints to access a specific tenant's data. GET /company always describes the authenticated key's own organization, so this endpoint is where per-tenant plan data is read.

GET /learners

List learners.

Returns learner records for the authenticated organization. Use this endpoint to sync learner rosters, status, group membership, and risk-level indicators into client systems. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

POST /learners

Create a learner.

Creates one learner in the authenticated organization. Email is required, free-email providers are rejected, and when domain lock is enabled the email must be on the company domain. Include group IDs when the learner should be added to existing learner groups during creation. Email-less ("User ID") learners — for people without an email who use the User ID Access Portal — cannot be created through this API and must be added via the dashboard. This endpoint changes organization data and requires an authorized bearer token.

Request body

DELETE /learners/{learnerId}

Delete a learner.

Deletes a learner from the authenticated organization. Use this only when the learner should be permanently removed from SiberMate workflows. This endpoint changes organization data and should be called only from trusted server-side systems.

Parameters

GET /learners/{learnerId}

Retrieve learner details.

Returns a single learner record, including profile fields, active status, locale, group membership, and available risk-level indicators. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

PATCH /learners/{learnerId}

Update a learner.

Updates learner profile fields and optional group membership. Use this endpoint for HRIS or identity-driven learner profile synchronization. This endpoint changes organization data and requires an authorized bearer token.

Parameters

Request body

GET /learners/{learnerId}/breaches

Retrieve learner breach exposure.

Returns breach exposure linked to a single learner when breach monitoring data is available. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

GET /learners/{learnerId}/course-results

Retrieve learner course results.

Returns course-level training results for a learner, including enrolment, start, completion, score, and grade fields when available. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

GET /learners/{learnerId}/gap-analysis-results

Retrieve learner gap analysis results.

Returns gap analysis results for a learner so client systems can inspect assessment progress and outcomes. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

PUT /learners/{learnerId}/groups

Replace learner group membership.

Replaces the full set of groups assigned to a learner. Send the complete desired group list, not only the groups being added. This endpoint changes organization data and requires an authorized bearer token.

Parameters

Request body

GET /learners/{learnerId}/policy-results

Retrieve learner policy results.

Returns policy acknowledgement results for a learner. Optionally filter by policyId for a single policy. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

GET /learners/{learnerId}/simulation-queue

Retrieve learner simulation queue.

Returns pending or queued phishing simulation activity for a learner when available. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

GET /learners/{learnerId}/simulation-results

Retrieve learner simulation results.

Returns phishing simulation activity for a learner, suitable for learner-level security awareness reporting. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

POST /learners/activate

Activate learners.

Reactivates learners so they can receive training, policy, phishing simulation, and reporting workflows again. This endpoint changes organization data and requires an authorized bearer token.

Request body

DELETE /learners/bulk

Delete learners in bulk.

Deletes multiple learners in a single request. Use this only for controlled offboarding or organization cleanup workflows. This endpoint changes organization data and should be called only from trusted server-side systems.

Request body

POST /learners/bulk

Create learners in bulk.

Creates one or more learners in a single request for roster import or bulk synchronization. Email is required for every learner (same rules as POST /learners). externalLearnerId is an optional HRIS/source identifier for emailed learners. Email-less ("User ID") learners cannot be created through this API — add them via the dashboard. This endpoint changes organization data and should be called only from trusted server-side systems.

Request body

POST /learners/deactivate

Deactivate learners.

Deactivates learners without deleting their historical results. Use this for temporary leave, offboarding holds, or staged cleanup workflows. This endpoint changes organization data and requires an authorized bearer token.

Request body

POST /group-membership/move

Move learners from one group to another.

Move learners from one group to another. This endpoint changes organization data and requires an authorized bearer token.

Request body

GET /groups

List learner groups.

List learner groups. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

POST /groups

Create a learner group.

Creates a learner group and optionally assigns group managers. Pass parentGroupId to create it as a subgroup. Names must be unique among groups with the same parent (top-level groups count as siblings), ignoring case and surrounding spaces; a duplicate returns 409 GROUP_NAME_EXISTS with details.existingGroupId. The same name under a different parent is allowed. This endpoint changes organization data and requires an authorized bearer token.

Request body

DELETE /groups/{groupId}

Delete a learner group.

Deletes a learner group from the organization. Confirm downstream automations no longer depend on the group before deletion. This endpoint changes organization data and should be called only from trusted server-side systems.

Parameters

GET /groups/{groupId}

Retrieve group details.

Retrieve group details. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

POST /groups/{groupId}/learners/add

Add learners to a group, keeping their existing groups.

Add learners to a group, keeping their existing groups. This endpoint changes organization data and requires an authorized bearer token.

Parameters

Request body

POST /groups/{groupId}/learners/remove

Remove learners from a group, keeping their other groups.

Remove learners from a group, keeping their other groups. This endpoint changes organization data and requires an authorized bearer token.

Parameters

Request body

PUT /groups/{groupId}/managers

Replace group managers.

Replaces the manager list for a learner group. Send the complete desired manager list. This endpoint changes organization data and requires an authorized bearer token.

Parameters

Request body

POST /course-enrollments

Assign courses to learners.

Assigns one or more courses to one or more learners and emails them. A learner already enrolled in a course is not enrolled again: SiberMate sends them a reminder email instead, reported as action "reminder" in the result (this endpoint and /course-reminders share one upstream operation). This endpoint changes organization data and requires an authorized bearer token.

Request body

POST /course-reminders

Send course reminders.

Sends reminders to learners with outstanding course work. This is exposed separately from course assignment for clearer client automation. This endpoint changes organization data and requires an authorized bearer token.

Request body

POST /course-unenrollments

Remove course assignments.

Removes course assignments from learners when they should no longer complete those courses. This endpoint changes organization data and requires an authorized bearer token.

Request body

GET /courses

List training courses.

Returns managed catalog courses and courses owned by the authenticated organization. Courses owned by other tenants are filtered out even if the upstream catalog endpoint returns them. Use source to separate managed catalog courses from organization-created courses, and type to separate standard training from gap analysis courses. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

GET /courses/{courseId}

Retrieve course details.

Returns a global catalog course or a course owned by the authenticated organization. Courses owned by another tenant return 404. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

POST /gap-analysis/enrollments

Assign gap analysis to learners.

Assigns gap analysis to learners and emails them. A learner already assigned is not assigned again: SiberMate sends them a reminder email instead (this endpoint and /gap-analysis/reminders share one upstream operation). This endpoint changes organization data and requires an authorized bearer token.

Request body

POST /gap-analysis/reminders

Send gap analysis reminders.

Sends reminders to learners with outstanding gap analysis work. This endpoint changes organization data and requires an authorized bearer token.

Request body

POST /gap-analysis/unenrollments

Remove gap analysis assignments.

Removes gap analysis assignments from learners. This endpoint changes organization data and requires an authorized bearer token.

Request body

GET /reports/course-participation

Retrieve course participation report.

Retrieve course participation report. This endpoint returns data for the organization associated with the authenticated API key. Reports aggregate data across the whole organization, so on large organizations a request can take up to about 40 seconds. Identical requests made with the same API key within 2 minutes are answered from a short-lived cache (the x-sibermate-cache response header reads hit), so the data can be up to 2 minutes old; a successful write made with the same API key clears that key's cached reports. Call a report once per run and reuse the result. On a 504 or 503, wait for the Retry-After header before retrying instead of retrying immediately.

Parameters

GET /reports/course-results

Retrieve course results report.

Retrieve course results report. This endpoint returns data for the organization associated with the authenticated API key. Reports aggregate data across the whole organization, so on large organizations a request can take up to about 40 seconds. Identical requests made with the same API key within 2 minutes are answered from a short-lived cache (the x-sibermate-cache response header reads hit), so the data can be up to 2 minutes old; a successful write made with the same API key clears that key's cached reports. Call a report once per run and reuse the result. On a 504 or 503, wait for the Retry-After header before retrying instead of retrying immediately. Large organizations should page or summarize instead of downloading every row at once. Without limit, cursor, or view the full report is returned as an array, as before. With limit (and then cursor), each response carries one page plus pagination.total and pagination.nextCursor; pass nextCursor as cursor until it is null. Rows are ordered by learner, then course or simulation, and a cursor stays valid when rows change between pages. view=summary returns totals instead of rows (see the view parameter); includeSummary=true adds the same totals to a paged response. Responses are gzip-compressed when the request sends Accept-Encoding: gzip; a response that would still exceed the 4.5 MB delivery limit returns 413 RESPONSE_TOO_LARGE, which paging avoids.

Parameters

GET /reports/gap-analysis-results

Retrieve gap analysis results report.

Retrieve gap analysis results report. This endpoint returns data for the organization associated with the authenticated API key. Reports aggregate data across the whole organization, so on large organizations a request can take up to about 40 seconds. Identical requests made with the same API key within 2 minutes are answered from a short-lived cache (the x-sibermate-cache response header reads hit), so the data can be up to 2 minutes old; a successful write made with the same API key clears that key's cached reports. Call a report once per run and reuse the result. On a 504 or 503, wait for the Retry-After header before retrying instead of retrying immediately. Large organizations should page or summarize instead of downloading every row at once. Without limit, cursor, or view the full report is returned as an array, as before. With limit (and then cursor), each response carries one page plus pagination.total and pagination.nextCursor; pass nextCursor as cursor until it is null. Rows are ordered by learner, then course or simulation, and a cursor stays valid when rows change between pages. view=summary returns totals instead of rows (see the view parameter); includeSummary=true adds the same totals to a paged response. Responses are gzip-compressed when the request sends Accept-Encoding: gzip; a response that would still exceed the 4.5 MB delivery limit returns 413 RESPONSE_TOO_LARGE, which paging avoids.

Parameters

GET /reports/learning

Retrieve learning report.

Returns organization-level learning report data for executive dashboards, periodic exports, or internal compliance reporting. This endpoint returns data for the organization associated with the authenticated API key. Reports aggregate data across the whole organization, so on large organizations a request can take up to about 40 seconds. Identical requests made with the same API key within 2 minutes are answered from a short-lived cache (the x-sibermate-cache response header reads hit), so the data can be up to 2 minutes old; a successful write made with the same API key clears that key's cached reports. Call a report once per run and reuse the result. On a 504 or 503, wait for the Retry-After header before retrying instead of retrying immediately.

Parameters

GET /reports/risk-score-history

Retrieve risk score history.

Returns daily risk scores for the requested date range as four series: Company (riskScore), smbreach (breachRiskScore), smphish (phishRiskScore), and smlearn (smlearnRiskScore). Without fromDate and toDate the whole history is returned, one point per day. This endpoint returns data for the organization associated with the authenticated API key. Reports aggregate data across the whole organization, so on large organizations a request can take up to about 40 seconds. Identical requests made with the same API key within 2 minutes are answered from a short-lived cache (the x-sibermate-cache response header reads hit), so the data can be up to 2 minutes old; a successful write made with the same API key clears that key's cached reports. Call a report once per run and reuse the result. On a 504 or 503, wait for the Retry-After header before retrying instead of retrying immediately.

Parameters

GET /reports/simulation-results

Retrieve phishing simulation results report.

Returns every learner's result in every phishing simulation, one row per learner per simulation: when they opened the email, visited the link, were compromised, and reported it (null when they did not). Use it for questions across learners, such as who was compromised in a campaign or who keeps clicking, instead of reading GET /learners/{learnerId}/simulation-results for each learner. view=summary gives the same counts per simulation, newest first. This endpoint returns data for the organization associated with the authenticated API key. Reports aggregate data across the whole organization, so on large organizations a request can take up to about 40 seconds. Identical requests made with the same API key within 2 minutes are answered from a short-lived cache (the x-sibermate-cache response header reads hit), so the data can be up to 2 minutes old; a successful write made with the same API key clears that key's cached reports. Call a report once per run and reuse the result. On a 504 or 503, wait for the Retry-After header before retrying instead of retrying immediately. Large organizations should page or summarize instead of downloading every row at once. Without limit, cursor, or view the full report is returned as an array, as before. With limit (and then cursor), each response carries one page plus pagination.total and pagination.nextCursor; pass nextCursor as cursor until it is null. Rows are ordered by learner, then course or simulation, and a cursor stays valid when rows change between pages. view=summary returns totals instead of rows (see the view parameter); includeSummary=true adds the same totals to a paged response. Responses are gzip-compressed when the request sends Accept-Encoding: gzip; a response that would still exceed the 4.5 MB delivery limit returns 413 RESPONSE_TOO_LARGE, which paging avoids.

Parameters

GET /policies

List policies.

List policies. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

POST /policies

Create a policy.

Creates a policy as a draft or live policy, depending on the submitted action. This endpoint changes organization data and requires an authorized bearer token.

Request body

GET /policies/{policyId}

Retrieve policy details.

Retrieve policy details. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

PATCH /policies/{policyId}

Update a policy.

Updates an existing policy. Use draft and publish endpoints when you need a controlled policy review workflow. This endpoint changes organization data and requires an authorized bearer token.

Parameters

Request body

POST /policies/{policyId}/discard-draft

Discard a policy draft.

Discards the current draft version and keeps the existing live policy unchanged. This endpoint changes organization data and requires an authorized bearer token.

Parameters

POST /policies/{policyId}/publish-draft

Publish a policy draft.

Publishes the current draft version of a policy. This endpoint changes organization data and requires an authorized bearer token.

Parameters

Request body

DELETE /policies/bulk

Delete policies in bulk.

Delete policies in bulk. This endpoint changes organization data and should be called only from trusted server-side systems.

Request body

POST /policies/from-template

Create a policy from a template.

Creates an organization policy from a SiberMate policy template. This endpoint changes organization data and requires an authorized bearer token.

Request body

POST /policies/upload

Upload a policy PDF.

Uploads a policy PDF and returns the file reference used when creating or updating policy records. This endpoint changes organization data and should be called only from trusted server-side systems.

Request body

POST /policy-assignments

Assign policies to learners.

Assigns one or more policies to one or more learners and emails them. A learner already assigned a policy is not assigned again: SiberMate sends them a reminder email instead (this endpoint and /policy-reminders share one upstream operation). This endpoint changes organization data and requires an authorized bearer token.

Request body

POST /policy-reminders

Send policy reminders.

Sends reminders to learners with outstanding policy acknowledgements. This endpoint changes organization data and requires an authorized bearer token.

Request body

POST /policy-removals

Remove policy assignments.

Removes learners from one or more policy assignments. This endpoint changes organization data and requires an authorized bearer token.

Request body

GET /policy-templates

List policy templates.

Returns available policy templates that can be used to create organization policies. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

POST /policy-templates

Create policy template.

Creates a reusable policy template from an uploaded PDF key. Templates are blueprints: publishing one makes it selectable but sends nothing to learners until a policy is created from it. For MSP and Distributor keys, global shares the template with every child tenant and companies limits it to specific tenants. This endpoint changes organization data and requires an authorized bearer token.

Request body

GET /policy-templates/{policyTemplateId}

Retrieve policy template details.

Retrieve policy template details. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

PATCH /policy-templates/{policyTemplateId}

Update policy template.

Updates a policy template or its draft. Available to MSP and Distributor keys only — SiberMate rejects template updates from tenant and prospect accounts, which can still create, publish, and delete templates. This endpoint changes organization data and requires an authorized bearer token.

Parameters

Request body

POST /policy-templates/{policyTemplateId}/discard-draft

Discard policy template draft.

Discards the draft version of a policy template and keeps the published version. This endpoint changes organization data and requires an authorized bearer token.

Parameters

POST /policy-templates/{policyTemplateId}/publish-draft

Publish policy template draft.

Publishes the draft version of a policy template, making it selectable for policy creation. This endpoint changes organization data and requires an authorized bearer token.

Parameters

DELETE /policy-templates/bulk

Delete policy templates in bulk.

Permanently removes policy templates owned by the organization. This endpoint changes organization data and should be called only from trusted server-side systems.

Request body

GET /simulations

List phishing simulations.

List phishing simulations. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

GET /simulations/{simulationId}

Retrieve phishing simulation details.

Retrieve phishing simulation details. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

GET /simulations/domains

List active phishing simulation domains.

Returns the domains currently active for SiberMate phishing simulations. The list is the same for every organization, so companyId does not apply. Use it to keep email-security and web-filter allowlists current: a domain missing from this list is no longer active.

GET /simulations/metrics

Retrieve phishing simulation metrics.

Returns aggregate phishing simulation metrics for organization-level reporting. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

GET /simulations/performance

Retrieve phishing rates per simulation.

Returns the open, visit, compromise, and report rate of each sent phishing simulation, oldest startDate first, for trend charts. Rates are unrounded fractions of total recipients (0.25 means 25%). Simulations that have not been sent yet are not listed. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

GET /breaches/accounts

List exposed accounts.

Returns exposed account data when breach monitoring data is available. This endpoint returns data for the organization associated with the authenticated API key.

Parameters

GET /breaches/services

List breached services.

Returns breached services and affected-account counts when breach monitoring data is available. This endpoint returns data for the organization associated with the authenticated API key.

Parameters