# Primo Documentation: English Developers ## Developers ### Get started - [Create API keys for Primo](https://docs.getprimo.com/api/create-primo-api-key.md): Generate a Primo API key to authenticate requests to the Primo REST API. - [Create API keys for Fleet](https://docs.getprimo.com/api/create-fleet-api-key.md): Generate a Fleet API key to authenticate direct requests to your Fleet instance. - [Connect to our MCP](https://docs.getprimo.com/get-started/primo-mcp-server.md): Connect ChatGPT, Claude, Cursor, and other AI assistants to the Primo Model Context Protocol (MCP) server to manage your IT fleet in natural language. ### API Reference #### Admins - [Get all admins](https://docs.getprimo.com/api-reference/admins/get-all-admins.md): Return the list of admin users for your company. Each entry is either an employee (with an id) or an external user (with its userId, the id a ticket carries for an EXTERNAL_ADMIN actor). roleName is the Clerk role key. - [Email the company admins](https://docs.getprimo.com/api-reference/admins/email-the-company-admins.md): Send an email to the admins of your company. Recipients can only be admins of your own company: either the ones named in adminIds, or all of them when adminIds is omitted. There is no way to email any other address. #### Company - [Get the authenticated company](https://docs.getprimo.com/api-reference/company/get-the-authenticated-company.md): Return the company associated with the API key. Only accessible with a Company API key. - [Get the company metrics report](https://docs.getprimo.com/api-reference/company/get-the-company-metrics-report.md): Return the KPI report of the authenticated company as JSON: use it to summarise the company's situation, build a report or answer how-many questions at a glance. `report` holds the headline counts (devices in use, assigned or not, and in stock; employees to enroll or enrolled; devices with MDM on, o… #### CustomFields - [List custom fields](https://docs.getprimo.com/api-reference/customfields/list-custom-fields.md): Return a paginated list of custom field definitions for your company — definitions only, without the values stored on entities. To read or write the values on a specific entity, use `getDeviceCustomFields`/`getDevicesCustomFields` (devices) or `getAccessoryCustomFields` (accessories). Defaults to AC… - [Create a custom field](https://docs.getprimo.com/api-reference/customfields/create-a-custom-field.md): Create a new custom field definition. Labels are not constrained to be unique. Options are only allowed for SELECT and MULTI_SELECT field types. - [Get a custom field by ID](https://docs.getprimo.com/api-reference/customfields/get-a-custom-field-by-id.md): Return the custom field definition for the given custom field ID — the definition only, not the values stored on entities. To read or write values, use the per-entity endpoints (`getDeviceCustomFields`, `getAccessoryCustomFields`, …). - [Update a custom field](https://docs.getprimo.com/api-reference/customfields/update-a-custom-field.md): Update label, applyTo (widen-only), optionsToAdd, or optionsToRename on a custom field. At least one field must be provided. Archived fields cannot be updated. - [Archive a custom field](https://docs.getprimo.com/api-reference/customfields/archive-a-custom-field.md): Archive a custom field definition. Archived fields are no longer offered for new values but remain readable. Returns 409 if the field has active consumers (related entities must be cleared first). #### Workspace - [Get all companies in the workspace](https://docs.getprimo.com/api-reference/workspace/get-all-companies-in-the-workspace.md): Return the list of companies in your workspace. Only accessible with a Workspace API key. - [Create a company in the workspace](https://docs.getprimo.com/api-reference/workspace/create-a-company-in-the-workspace.md): Create a company in your workspace as a draft. Nothing is provisioned yet: configure its options, then activate it. The name must be unique across Primo and the domain unique within your workspace. Only accessible with a Workspace API key. - [Get a company by ID](https://docs.getprimo.com/api-reference/workspace/get-a-company-by-id.md): Return the company details for the given company ID, including its status and its subscription options. Answers for a company that is still a draft. Only accessible with a Workspace API key. - [Update the options of a draft company](https://docs.getprimo.com/api-reference/workspace/update-the-options-of-a-draft-company.md): Update the subscription options of a company that has not been activated yet. Only the fields you send are changed. Activation closes this endpoint: an activated company answers 409 and its configuration is then managed from the Primo cockpit. Only accessible with a Workspace API key. - [Activate a draft company](https://docs.getprimo.com/api-reference/workspace/activate-a-draft-company.md): Activate a draft company: it becomes usable, its administrators are granted access, and it starts being billed according to its options. Irreversible, and the options can no longer be changed through the API afterwards. Only accessible with a Workspace API key. #### Devices - [Get all devices (deprecated)](https://docs.getprimo.com/api-reference/devices/get-all-devices-deprecated.md): **Deprecated** — use `getDevices` (`POST /devices/search`) instead, which returns the same device objects and additionally accepts a filter and a free-text search. This route will be removed on 2026-11-01. Return the paginated list of devices for your company, retired ones excluded, as JSON. - [Create a device](https://docs.getprimo.com/api-reference/devices/create-a-device.md): Create a new device in your company. - [Update several devices](https://docs.getprimo.com/api-reference/devices/update-several-devices.md): Update the inventory data of MULTIPLE devices in one call — the batch form of `updateDevice`, with the same fields and the same rules per device. Provide a list of `items`, each targeting one `deviceId` (up to 100 per call, each device at most once). Writes are independent and best-effort: the call… - [Export devices as CSV](https://docs.getprimo.com/api-reference/devices/export-devices-as-csv.md): Export the devices of your company as a paginated CSV (one row per device, first line is the header, up to 1000 devices per page). Each row contains the device attributes, its latest code of each type (recovery key, iCloud bypass code, unlock PIN, recovery OS password — see `getDeviceCodeHistory` fo… - [Get the device search filter catalog](https://docs.getprimo.com/api-reference/devices/get-the-device-search-filter-catalog.md): Return every criterion a device filter accepts — each with its `key`, `valueType`, allowed operations and live company values — plus the custom fields defined for devices. This is the vocabulary for `getDevices`: use a criterion's `key` as the filter key and one of its `values` inside the clause (`{… - [Get a device by ID](https://docs.getprimo.com/api-reference/devices/get-a-device-by-id.md): Return the device details for the given device ID. This device can have custom fields (see `getDeviceCustomFields`) and code history (see `getDeviceCodeHistory`). This device can also have local user accounts (see `getDeviceUsers`). - [Delete a device](https://docs.getprimo.com/api-reference/devices/delete-a-device.md): Permanently delete a device from your company. The device must not be enrolled. - [Update a device](https://docs.getprimo.com/api-reference/devices/update-a-device.md): Update the inventory data of one device: its assignee, its identity and specs, and its purchase data. Only the fields present in the body are changed — each field documents its own constraints. Fields that MDM reports for an enrolled device can only be set while the device is not enrolled; changing… - [Lock a device](https://docs.getprimo.com/api-reference/devices/lock-a-device.md): Lock the device for the given device ID. - [Unlock a device](https://docs.getprimo.com/api-reference/devices/unlock-a-device.md): Unlock the device for the given device ID. - [Wipe a device](https://docs.getprimo.com/api-reference/devices/wipe-a-device.md): Wipe the device for the given device ID. - [Run a script on one device](https://docs.getprimo.com/api-reference/devices/run-a-script-on-one-device.md): Run a script on the device for the given device ID. Pass `{ "scriptId": 12 }` to run a saved script (see `getScripts`), or `{ "contents": "..." }` to send the source inline. - [List a device's script history](https://docs.getprimo.com/api-reference/devices/list-a-devices-script-history.md): Return the paginated script executions that reached this device, newest first — across every run, including company-wide and device-group runs launched elsewhere. Each entry carries the script that ran plus its status, output, exit code and runtime. Use this to answer "what has been run on this mach… - [Retire a device](https://docs.getprimo.com/api-reference/devices/retire-a-device.md): Retire (decommission) a device: it is unassigned from its owner, renamed to `deviceName`, marked retired and taken out of stock, with `condition` and `notes` recorded; `putDeviceBackInStock` reverts it. The device must not be enrolled in MDM: an enrolled device is refused with 409, but the unassignm… - [Reboot a device](https://docs.getprimo.com/api-reference/devices/reboot-a-device.md): Trigger a reboot on the device. The command is sent the next time the device comes online. - [Disenroll a device](https://docs.getprimo.com/api-reference/devices/disenroll-a-device.md): Disenroll the device from MDM; once done, the device is no longer managed. Android is disenrolled immediately. On macOS, Windows and Linux a removal script runs when the device next checks in, so it still reads as enrolled until then; other platforms cannot be disenrolled remotely and are refused wi… - [Move a device to stock](https://docs.getprimo.com/api-reference/devices/move-a-device-to-stock.md): Move the device to stock (unassign it from any employee). - [Move a device to in-use](https://docs.getprimo.com/api-reference/devices/move-a-device-to-in-use.md): Move the device from stock back to in-use status. - [Put a device back in stock](https://docs.getprimo.com/api-reference/devices/put-a-device-back-in-stock.md): Cancel a pending retirement and return the device to stock. - [Update a device owner](https://docs.getprimo.com/api-reference/devices/update-a-device-owner.md): Assign or unassign a device to an employee. Pass null to unassign. - [Update device tags](https://docs.getprimo.com/api-reference/devices/update-device-tags.md): Replace the tags on a device with the provided list. - [Get device events](https://docs.getprimo.com/api-reference/devices/get-device-events.md): Return the list of lifecycle events recorded by Primo for the given device (lock, wipe, reboot, disenroll, etc.) in reverse chronological order. For the MDM activity feed reported by the MDM layer, use `getDeviceActivities`; for raw MDM protocol commands and their delivery status, use `getDeviceComm… - [List local user accounts on a device](https://docs.getprimo.com/api-reference/devices/list-local-user-accounts-on-a-device.md): Return the local user accounts provisioned on ONE device, each with its privilege level (`rights`: ADMIN / USER / UNKNOWN). Use this to find which accounts hold local administrator or standard user rights on a machine. For many devices at once, use `getDevicesUsers` instead of calling this endpoint… - [List local user accounts on multiple devices](https://docs.getprimo.com/api-reference/devices/list-local-user-accounts-on-multiple-devices.md): Return the local user accounts provisioned on MULTIPLE devices in one call, grouped by device id, each account with its privilege level (`rights`: ADMIN / USER / UNKNOWN). Use this to answer fleet-wide questions such as "which users hold local administrator rights on their machine": list the devices… - [Get device code history](https://docs.getprimo.com/api-reference/devices/get-device-code-history.md): Return the decrypted code history for ONE device (recovery key, iCloud bypass code, unlock PIN, recovery OS password), newest first. Optionally filter by `type`. For many devices at once, use `getDevicesCodeHistory` instead of calling this endpoint in a loop. - [Get code history for multiple devices](https://docs.getprimo.com/api-reference/devices/get-code-history-for-multiple-devices.md): Return the decrypted code history (recovery key, iCloud bypass code, unlock PIN, recovery OS password) for MULTIPLE devices in one call, grouped by device id, each newest first. Provide a list of `deviceIds` (up to 200 per call), optionally filtered by `type`. Devices that do not exist, or that do n… - [Get device custom fields](https://docs.getprimo.com/api-reference/devices/get-device-custom-fields.md): Return all Active custom field definitions for ONE device, each paired with the current stored value (or null when unset). For SELECT / MULTI_SELECT fields the `options` catalog is included so you can map option ids to labels. For many devices at once, use `getDevicesCustomFields` instead of calling… - [Get custom fields for multiple devices](https://docs.getprimo.com/api-reference/devices/get-custom-fields-for-multiple-devices.md): Return all Active custom field definitions for MULTIPLE devices in one call, each paired with the current stored value (or null when unset), grouped by device id. Provide a list of `deviceIds` (up to 500 per call). Prefer this over calling `getDeviceCustomFields` once per device. - [Set a device custom field value](https://docs.getprimo.com/api-reference/devices/set-a-device-custom-field-value.md): Set or overwrite a custom field value on a device. Idempotent. Returns the updated field (definition + value). For SELECT supply the option id (string); for MULTI_SELECT supply an array of option ids. Option ids can be read from the `getDeviceCustomFields` endpoint. - [Clear a device custom field value](https://docs.getprimo.com/api-reference/devices/clear-a-device-custom-field-value.md): Remove the stored value for a custom field on a device. Returns the updated field (value reset to null). - [Get devices, optionally narrowed by a filter](https://docs.getprimo.com/api-reference/devices/get-devices-optionally-narrowed-by-a-filter.md): Return the devices of your company as a paginated JSON list of full device objects — use it to look up, filter, count or answer any question about devices. Send an empty body to list everything; add a `filter` to narrow it. Every `filter` entry is keyed by a `key` from `getDeviceFilterCatalog` (`GET… - [Set device custom field values in batch](https://docs.getprimo.com/api-reference/devices/set-device-custom-field-values-in-batch.md): Set, overwrite, or clear custom field values across many devices in one call. Provide a list of `items`, each targeting one (deviceId, customFieldId) pair with the `value` to write (null clears it). Each pair must be unique within the batch (duplicates are rejected with 400). Up to 100 items per cal… - [List software on a device](https://docs.getprimo.com/api-reference/devices/list-software-on-a-device.md): Return the paginated list of Primo-managed software installed on or targeted for ONE device, each with its install status (installed, in_progress, failed, not_installed), installed/available versions, and the actions available on it (whether install/update can run and why not, whether it can be unin… - [List the MDM controls that apply to a device](https://docs.getprimo.com/api-reference/devices/list-the-mdm-controls-that-apply-to-a-device.md): Return the complete list of enabled MDM controls that TARGET ONE device — the policies this machine is meant to receive (disk encryption, screen lock, OS restrictions, installed profiles…), each with its id, name, type, platform, tags and how it reaches the device (`targetMethod`). Targeting only: a… - [Get software install logs on a device](https://docs.getprimo.com/api-reference/devices/get-software-install-logs-on-a-device.md): Return every install attempt of ONE software on ONE device, newest first (up to the 20 most recent): status, script/query output for a package, the decoded MDM error for an App Store app, when it ran, and what triggered it (`manual`, `selfService`, `policy` with its name, or `setupExperience`). MDM… - [Install a software on a device](https://docs.getprimo.com/api-reference/devices/install-a-software-on-a-device.md): Install ONE Primo-managed software on ONE device via MDM. The software must already exist in your company catalog (see `getSoftwares`) and be available for install on that device. To remove it instead, use `uninstallDeviceSoftware`. - [Uninstall a software from a device](https://docs.getprimo.com/api-reference/devices/uninstall-a-software-from-a-device.md): Uninstall ONE Primo-managed software from ONE device via MDM. Not all software supports uninstall. To install it instead, use `installDeviceSoftware`. - [Sync a device software state](https://docs.getprimo.com/api-reference/devices/sync-a-device-software-state.md): Trigger a resync of ONE device's software from the MDM provider (Fleet) so its install state (installed/failed/in_progress) is refreshed. Runs in the background; re-read with `getDeviceSoftware` afterwards. To resync the whole company catalog instead, use `syncCompanySoftwares`. This reads what the… - [List past activities for a device](https://docs.getprimo.com/api-reference/devices/list-past-activities-for-a-device.md): Return the paginated list of past MDM activities for a device, as reported by the MDM layer. The `details` field is a polymorphic passthrough whose shape varies by activity type. For device lifecycle events recorded by Primo (lock, wipe, retire…), use `getDeviceEvents` instead. - [List upcoming activities for a device](https://docs.getprimo.com/api-reference/devices/list-upcoming-activities-for-a-device.md): Return the paginated list of upcoming (queued) MDM activities for a device. The `details` field is a polymorphic passthrough whose shape varies by activity type. To clear one wedged item out of that queue (a stuck install blocking everything behind it), use `cancelDeviceUpcomingActivity` with the `u… - [Cancel a queued activity on a device](https://docs.getprimo.com/api-reference/devices/cancel-a-queued-activity-on-a-device.md): Cancel ONE activity still queued on a device — a pending software install or uninstall, or a queued script — identified by the `uuid` returned by `getDeviceUpcomingActivities`. Use this to clear an install that is wedged (a package install Fleet leaves `in_progress` for up to an hour after the devic… - [Resend one MDM control's configuration profile to one device](https://docs.getprimo.com/api-reference/devices/resend-one-mdm-controls-configuration-profile-to-one-device.md): Ask the MDM to deliver an MDM control's configuration profile to ONE device again — the remediation for a profile the device failed to apply, without re-applying the control to every device it targets. Take `mdmControlId` from the compliance alert, and call `getComplianceAlertDetails` first: it repo… - [Refresh Primo's record of a device from the MDM](https://docs.getprimo.com/api-reference/devices/refresh-primos-record-of-a-device-from-the-mdm.md): Pull ONE device's current state from the MDM into Primo — hardware and OS details, disk encryption, users, compliance and MDM/EDR status — and refresh the labels and assignment suggestions that depend on them. This is the Primo side of a device refresh: `refetchDevice` asks the device to re-report t… - [Ask a device to report its state back to the MDM](https://docs.getprimo.com/api-reference/devices/ask-a-device-to-report-its-state-back-to-the-mdm.md): Ask ONE device to re-report its details, software inventory and policy results to the MDM. This refreshes what the MDM knows about the device, NOT Primo's own device record: the MDM only flags the device, the report lands the next time it checks in, and Primo picks that state up later through its ow… - [List MDM commands for a device](https://docs.getprimo.com/api-reference/devices/list-mdm-commands-for-a-device.md): Return the paginated list of raw MDM protocol commands sent to a device, including their status (ran, pending, failed). Use `getDeviceCommandResults` for the execution results of one command. For a higher-level history, use `getDeviceActivities` (MDM activity feed) or `getDeviceEvents` (Primo lifecy… - [Get results for an MDM command](https://docs.getprimo.com/api-reference/devices/get-results-for-an-mdm-command.md): Return the execution results for a specific MDM command on a device. #### Scripts - [List the saved scripts](https://docs.getprimo.com/api-reference/scripts/list-the-saved-scripts.md): Return your company's saved scripts as JSON — id, name, and the platforms each one can run on. Use this to discover a `scriptId` before calling `runScript` or `runDeviceScript`. - [List script runs](https://docs.getprimo.com/api-reference/scripts/list-script-runs.md): Return the paginated history of script runs, newest first — what was run, on which target, by whom, and how many devices are in each execution status. Use this to answer "what scripts have been run recently?". - [Run a script on a target](https://docs.getprimo.com/api-reference/scripts/run-a-script-on-a-target.md): Run a script on all devices, on one or more device groups, or on an explicit list of devices — intersected with the given platforms. Pass `{ "scriptId": 12 }` to run a saved script (see `getScripts`), or `{ "contents": "..." }` to send the source inline. An inline run may only target a single device… - [Count the devices a script run would reach](https://docs.getprimo.com/api-reference/scripts/count-the-devices-a-script-run-would-reach.md): Return how many devices a run with this target and these platforms would resolve to, using exactly the same resolution as `runScript`. Nothing is executed. Call this before `runScript` to check the blast radius, especially with `target.type = "all"`. - [List the per-device results of a script run](https://docs.getprimo.com/api-reference/scripts/list-the-per-device-results-of-a-script-run.md): Return the paginated executions of one script run — one per targeted device, each with its status, output, exit code and runtime. Use this to see which devices succeeded and read the script output. - [Get a script run](https://docs.getprimo.com/api-reference/scripts/get-a-script-run.md): Return one script run: the script as executed (including its source), the resolved target, and the count of executions in each status. This is the endpoint to poll after `runScript` to follow progress. - [Get a saved script and its source](https://docs.getprimo.com/api-reference/scripts/get-a-saved-script-and-its-source.md): Return one saved script with its full source. Use this to review what a script does before running it. To list the available scripts, use `getScripts`. #### MdmControls - [Get all MDM controls](https://docs.getprimo.com/api-reference/mdmcontrols/get-all-mdm-controls.md): Return the list of MDM controls configured for your company — the device policies deployed to your fleet (disk encryption, screen lock, OS restrictions, installed profiles…) — with id, name, type, platform, tags, enabled, and target method. Use `getMdmControl` for one control's full configuration an… - [Create an MDM control](https://docs.getprimo.com/api-reference/mdmcontrols/create-an-mdm-control.md): Create a new MDM control of the given `type` with its `configurationPayload` and targeting. Discover creatable types and their config JSON Schema via GET /mdm-controls/catalog. `name` is optional — when omitted, the catalog default name for the type is used; supply a name to create several controls… - [Get the MDM control type catalog](https://docs.getprimo.com/api-reference/mdmcontrols/get-the-mdm-control-type-catalog.md): Return the catalog of all creatable MDM control types with their name, description, platform, category, activation status, and JSON Schema for the configuration payload. Intended for AI/MCP agents to discover which control types exist and how to configure them. - [Get an MDM control by ID](https://docs.getprimo.com/api-reference/mdmcontrols/get-an-mdm-control-by-id.md): Return MDM control details for the given control ID, including target details and configuration payload. - [Delete an MDM control](https://docs.getprimo.com/api-reference/mdmcontrols/delete-an-mdm-control.md): Delete an MDM control by ID. Removing the control undeploys it from every targeted device. An unknown ID returns 404. Demo companies are not allowed to delete MDM controls (403). - [Update an MDM control](https://docs.getprimo.com/api-reference/mdmcontrols/update-an-mdm-control.md): Partially update an existing MDM control by ID. Send only the fields you want to change — any omitted field is left unchanged. `type` is required and must match the control (it selects the config schema). Editable fields: `name`, `enabled`, `configurationPayload`, and targeting. `configurationPayloa… - [Update an MDM control's tags](https://docs.getprimo.com/api-reference/mdmcontrols/update-an-mdm-controls-tags.md): Replace the full set of tags on an MDM control. Send the complete desired tag list — any existing tag not included is removed. An unknown control ID returns 404. #### DeviceGroups - [Get all device groups](https://docs.getprimo.com/api-reference/devicegroups/get-all-device-groups.md): Return the list of device groups for your company (id, name). - [Create a device group](https://docs.getprimo.com/api-reference/devicegroups/create-a-device-group.md): Create a device group with a `name` and a `target` filter. `name` must be unique per company — a conflicting name is rejected with 409; `getDeviceGroups` (`GET /device-groups`) lists the existing names. Build the `target` from `getDeviceGroupFiltersOptions` (`GET /device-groups/filters-options`); `v… - [Get what uses a device group](https://docs.getprimo.com/api-reference/devicegroups/get-what-uses-a-device-group.md): List the softwares and MDM controls that target this device group. A group can only be deleted once both lists are empty — call this before DELETE to discover (and then remove) what still references it, or to explain a 409. - [Get the device group filter catalog](https://docs.getprimo.com/api-reference/devicegroups/get-the-device-group-filter-catalog.md): Return every criterion (native device attributes plus custom fields) that may target a device group, with its live company values inline. Use this to build a valid device-group target. This is a deliberately narrower set than the device **search** catalog (`getDeviceFilterCatalog`): a group targetin… - [Get a device group by ID](https://docs.getprimo.com/api-reference/devicegroups/get-a-device-group-by-id.md): Return the device group: its `target` filter (the same shape create/update accept) plus the device IDs that filter currently resolves to. Read the `target` here before a PUT to change one field while preserving the rest of the targeting. - [Update a device group](https://docs.getprimo.com/api-reference/devicegroups/update-a-device-group.md): Replace a device group's `name` and `target` filter. Both fields are required — send the full desired state, not a partial patch. `name` must be unique per company (a conflicting name is rejected with 409). Build the `target` from the `GET /device-groups/filters-options` catalog and check it with `v… - [Delete a device group](https://docs.getprimo.com/api-reference/devicegroups/delete-a-device-group.md): Delete a device group by ID. A group that is still targeted by an MDM control or a software is rejected with 409 — call `GET /device-groups/:deviceGroupId/relations` to see what references it and remove those first. An unknown ID returns 404; deleting an already-deleted group is a no-op that still r… - [Check a device group target before creating the group](https://docs.getprimo.com/api-reference/devicegroups/check-a-device-group-target-before-creating-the-group.md): Validate a device group `target` without persisting anything: it reports whether the target is well-formed, whether every criterion is device-group-targetable (build it from `getDeviceGroupFiltersOptions`), and how many devices it currently matches — so a target that is valid but matches nothing is… #### Employees - [Get employees, optionally narrowed by a search](https://docs.getprimo.com/api-reference/employees/get-employees-optionally-narrowed-by-a-search.md): Return your company's employees as a paginated list. Pass `search` to turn a name or an email into the employee it refers to instead of paging: free text over first and last name, full name in either order, work email and personal email, ignoring case and accents, plus text and URL custom field valu… - [Create an employee](https://docs.getprimo.com/api-reference/employees/create-an-employee.md): Create a new employee in your company. This only creates the record: it never starts an onboarding. To onboard the joiner (ticket, email, SaaS provisioning and equipment steps), call `createOnboarding` with the returned employee id. - [Get an employee by ID](https://docs.getprimo.com/api-reference/employees/get-an-employee-by-id.md): Return the full details for one employee, including their personal address — use it as the HOME shipping address when ordering equipment for a remote employee. For office addresses, use `getCompanyAddresses` instead. It carries the same fields as `getEmployees` — `teams`, `jobs` and the MDM enrollme… - [Update an employee](https://docs.getprimo.com/api-reference/employees/update-an-employee.md): Update an employee: name, work and personal emails, phone, gender, picture, manager, employment type, job title, teams, work location, legal entity, home address, start date and termination date. Only the provided fields are changed; omitted fields are left untouched. - [Get employee custom fields](https://docs.getprimo.com/api-reference/employees/get-employee-custom-fields.md): Return all Active custom field definitions for the employee, each paired with the current stored value (or null when unset). For SELECT / MULTI_SELECT fields the `options` catalog is included so you can map option ids to labels. - [Hide an employee](https://docs.getprimo.com/api-reference/employees/hide-an-employee.md): Hide an employee from the company directory. Their onboarding and offboarding records are removed. - [Set an employee custom field value](https://docs.getprimo.com/api-reference/employees/set-an-employee-custom-field-value.md): Set or overwrite a custom field value on an employee. Idempotent. Returns the updated field (definition + value). For SELECT supply the option id (string); for MULTI_SELECT supply an array of option ids. Option ids can be read from the `getEmployeeCustomFields` endpoint. - [Clear an employee custom field value](https://docs.getprimo.com/api-reference/employees/clear-an-employee-custom-field-value.md): Remove the stored value for a custom field on an employee. Returns the updated field (value reset to null). - [Unhide an employee](https://docs.getprimo.com/api-reference/employees/unhide-an-employee.md): Make a previously hidden employee visible again in the company directory. - [Send an MDM enrollment request to an employee](https://docs.getprimo.com/api-reference/employees/send-an-mdm-enrollment-request-to-an-employee.md): Trigger the Primo-branded MDM enrollment invitation for the employee. By default it is sent to their work email; set `sendToPersonalEmail` to send it to their personal email instead. #### EquipmentPolicy - [Get the equipment policy](https://docs.getprimo.com/api-reference/equipmentpolicy/get-the-equipment-policy.md): Return the company equipment policy: the editable draft text, the published text (what the agent sees at runtime, or null if never published), and the publication status. Read this before updating so you can re-send the full, edited body and diff draft against published. - [Get the computed equipment policy result](https://docs.getprimo.com/api-reference/equipmentpolicy/get-the-computed-equipment-policy-result.md): Return the computed equipment policy result: the recommended device and accessory product IDs per country, each country compute status (computing / ready / failed), and whether a policy is set up. The compute is asynchronous and fanned out per country, so a country can be `computing` while others ar… #### PurchasingPolicy - [Get the purchasing policy](https://docs.getprimo.com/api-reference/purchasingpolicy/get-the-purchasing-policy.md): Return the company purchasing policy: the editable draft text, the published text (what the agent sees at runtime, or null if never published), and the publication status. Read this before updating so you can re-send the full, edited body and diff draft against published. #### Accessories - [Get accessories, optionally narrowed to stock and to one type](https://docs.getprimo.com/api-reference/accessories/get-accessories-optionally-narrowed-to-stock-and-to-one-type.md): Return the list of accessories for your company. Pass `unassigned: true` to see only what is in stock — nobody owns it, so it can be handed out — and `type` to keep only one kind of accessory, so a request for a spare keyboard does not page through the whole inventory. The two combine: `unassigned:… - [Create an accessory](https://docs.getprimo.com/api-reference/accessories/create-an-accessory.md): Create an accessory for your company. - [Get an accessory by ID](https://docs.getprimo.com/api-reference/accessories/get-an-accessory-by-id.md): Return the accessory details for the given accessory ID. - [Update an accessory](https://docs.getprimo.com/api-reference/accessories/update-an-accessory.md): Update an existing accessory for your company. - [Get accessory custom fields](https://docs.getprimo.com/api-reference/accessories/get-accessory-custom-fields.md): Return all Active custom field definitions for the accessory, each paired with the current stored value (or null when unset). For SELECT / MULTI_SELECT fields the `options` catalog is included so you can map option ids to labels. - [Set an accessory custom field value](https://docs.getprimo.com/api-reference/accessories/set-an-accessory-custom-field-value.md): Set or overwrite a custom field value on an accessory. Idempotent. Returns the updated field (definition + value). For SELECT supply the option id (string); for MULTI_SELECT supply an array of option ids. Option ids can be read from the `getAccessoryCustomFields` endpoint. - [Clear an accessory custom field value](https://docs.getprimo.com/api-reference/accessories/clear-an-accessory-custom-field-value.md): Remove the stored value for a custom field on an accessory. Returns the updated field (value reset to null). - [Assign an accessory to an employee](https://docs.getprimo.com/api-reference/accessories/assign-an-accessory-to-an-employee.md): Assign an accessory to an employee. Pass ownerId as null to unassign the current owner. - [Archive an accessory](https://docs.getprimo.com/api-reference/accessories/archive-an-accessory.md): Archive (soft-delete) an accessory. The accessory is unassigned from its current owner and marked as deleted. #### Compliance - [Get all active compliance alerts](https://docs.getprimo.com/api-reference/compliance/get-all-active-compliance-alerts.md): Return the paginated list of active compliance alerts — one per (device, compliance rule) pair currently in a non-compliant status (e.g. not enrolled, offline, disk not encrypted). Each alert carries its device (`deviceId`, `deviceName`, `devicePlatform`, `owner`), its rule (`complianceRuleId`, `rul… - [Get compliance alerts, optionally narrowed by a filter](https://docs.getprimo.com/api-reference/compliance/get-compliance-alerts-optionally-narrowed-by-a-filter.md): Return the paginated list of active compliance alerts, narrowed by a `filter` — use it to answer any targeted question about non-compliance ("which macOS devices are not encrypted", "who owns the offline devices"). Send an empty body to list everything. Every `filter` entry is keyed by a `key` from… - [Get the full remediation context of one compliance alert](https://docs.getprimo.com/api-reference/compliance/get-the-full-remediation-context-of-one-compliance-alert.md): Return everything needed to diagnose and remediate one compliance alert (from `getComplianceAlerts`): the alert, the MDM control behind it with its configuration in clear, the device on both sides (`device.fleet` for the live MDM state — enrollment, last check-in, delivered profiles, failing checks;… - [Get the compliance alert a ticket was opened for, with its full remediation context](https://docs.getprimo.com/api-reference/compliance/get-the-compliance-alert-a-ticket-was-opened-for-with-its-full-remediation-context.md): Start here when working a compliance ticket: it answers what this ticket is about. Return the same payload as `getComplianceAlertDetails` — the alert, its MDM control with the configuration in clear, the device on both sides and the `enforcement` facets to remediate — for the alert that opened the t… - [Get the compliance alert filter catalog](https://docs.getprimo.com/api-reference/compliance/get-the-compliance-alert-filter-catalog.md): Return every criterion a compliance alert filter accepts — each with its `key`, `valueType`, allowed operations and live company values (the devices, platforms and owners that currently have an alert). This is the vocabulary for `searchComplianceAlerts`: use a criterion `key` as the filter key and o… - [Get all compliance alert rules](https://docs.getprimo.com/api-reference/compliance/get-all-compliance-alert-rules.md): Return the compliance rules of your company — the "Issue Triggers" page of the cockpit. One rule per compliance type (e.g. MDM_ENROLLMENT, MDM_ONLINE, MDM_CONTROL_ENCRYPTION); for each of its statuses, the cockpit shows Off, Create Issue or Create Issue and Ticket: a status in `nonCompliantStatus` r… - [Create or upsert a compliance alert rule](https://docs.getprimo.com/api-reference/compliance/create-or-upsert-a-compliance-alert-rule.md): Create a compliance alert rule for the given type. Each (company, type) pair is unique — calling this for an existing type overwrites its `nonCompliantStatus`, and its `ticketCreationStatus` when you send one. Every rule type already exists once a device was checked, so prefer `updateComplianceAlert… - [Update a compliance alert rule](https://docs.getprimo.com/api-reference/compliance/update-a-compliance-alert-rule.md): Set, per status of one compliance rule, what the cockpit shows as Off / Create Issue / Create Issue and Ticket: `nonCompliantStatus` lists every status that raises an issue, `ticketCreationStatus` the ones among them that also open a ticket. Send the full lists — read the rule with `getComplianceAle… #### Tasks - [Get all tasks](https://docs.getprimo.com/api-reference/tasks/get-all-tasks.md): Return a paginated list of tasks (child tickets) for your company. Pass a task id to getTicket to fetch that single task. - [Create a task](https://docs.getprimo.com/api-reference/tasks/create-a-task.md): Create a manual task on an existing ticket. Tasks cannot be added to onboarding tickets (whose tasks are managed automatically). - [Schedule a dormant task for later on your own ticket](https://docs.getprimo.com/api-reference/tasks/schedule-a-dormant-task-for-later-on-your-own-ticket.md): Plan work for later on the ticket you are currently working: creates a dormant task that wakes on the given date, instead of writing "I will check back on Monday" in a comment and forgetting. System agent transport only — refused for a human MCP token or a REST API key. You may only schedule on the… - [Update task status](https://docs.getprimo.com/api-reference/tasks/update-task-status.md): Mark a task as COMPLETED or CANCELLED. A task that completes by executing its intent refuses COMPLETED with a 403 `TaskLockedByTypeError` whose message names the operation to call instead (`executeEquipmentOrderIntent` for an EQUIPMENT_ORDER task, `executeEmployeeCreationIntent` for an EMPLOYEE_CREA… - [Update task assignee](https://docs.getprimo.com/api-reference/tasks/update-task-assignee.md): Assign a task to an employee. Provide the parent ticketId in the body. #### Tickets - [Get all tickets](https://docs.getprimo.com/api-reference/tickets/get-all-tickets.md): Return a paginated list of your company tickets — top-level tickets only; list tasks with `getTasks`. `searchTerm` matches a case-insensitive substring of the title or description, or a ticket reference (`IT-1741` or `1741`) — the way to turn a displayed reference into the 24-character ticket `id` t… - [Create a ticket](https://docs.getprimo.com/api-reference/tickets/create-a-ticket.md): Create a ticket for your company. Only `title` is required, and there is no description field on creation: set the ticket description afterwards with `updateTicket`, or post the details with `createTicketComment`. Link the device, employee or other records it concerns with `linkTicketRelatedObject`. - [Get a ticket by ID](https://docs.getprimo.com/api-reference/tickets/get-a-ticket-by-id.md): Return details for a specific ticket. A task is a child ticket — pass a task id here to fetch a single task. - [Update a ticket](https://docs.getprimo.com/api-reference/tickets/update-a-ticket.md): Partially update a ticket. Only the provided fields are changed (title, description, priority, dueDate, assignee, tags). Use updateTicketStatus to change the status. - [Update ticket status](https://docs.getprimo.com/api-reference/tickets/update-ticket-status.md): Set the status of an existing ticket. Its tasks are left as they are — close each one with `updateTaskStatus`. A ticket whose status follows its tasks (onboarding and offboarding tickets) is refused with 403. - [Update ticket assignee](https://docs.getprimo.com/api-reference/tickets/update-ticket-assignee.md): Assign a ticket to an employee. The assignee is a person; to put an AI agent on the ticket or take it off, use `updateTicketAiAgent` instead. - [Update the AI agent on a ticket](https://docs.getprimo.com/api-reference/tickets/update-the-ai-agent-on-a-ticket.md): Put an AI agent on a ticket, or take the one currently on it off by passing `aiAgentId: null`. The AI agent is the autonomous agent working the ticket, not its assignee — to assign the ticket to a person, use `updateTicketAssignee` instead. An agent puts itself on a ticket by passing its own agent i… - [Update ticket priority](https://docs.getprimo.com/api-reference/tickets/update-ticket-priority.md): Update the priority of an existing ticket. - [Create a ticket comment](https://docs.getprimo.com/api-reference/tickets/create-a-ticket-comment.md): Create a comment on a ticket. Comments are INTERNAL by default (team-only, never shown to the requester); pass visibility PUBLIC to post a requester-facing reply. Set taskId to reference the ticket task the comment concerns, and mention people in the text with @[Display Name](employee:)… - [Link a related object to a ticket](https://docs.getprimo.com/api-reference/tickets/link-a-related-object-to-a-ticket.md): Attach a device, employee, SaaS identity, order, shipment or SaaS application to the ticket. For `IDENTITY` pass the SaaS identity id (`identityId` from `getEmployeeSaasIdentities`), for `COMPANY_SAAS_APPLICATION` the company SaaS application id (`id` from `getSaas`). The response carries the `linkI… - [Unlink a related object from a ticket](https://docs.getprimo.com/api-reference/tickets/unlink-a-related-object-from-a-ticket.md): Detach a previously linked object from the ticket, using the linkId returned when listing or linking. - [List subscribers of a ticket](https://docs.getprimo.com/api-reference/tickets/list-subscribers-of-a-ticket.md): Return all subscribers for a specific ticket. - [Add subscribers to a ticket](https://docs.getprimo.com/api-reference/tickets/add-subscribers-to-a-ticket.md): Add one or more subscribers to an existing ticket. - [Remove a subscriber from a ticket](https://docs.getprimo.com/api-reference/tickets/remove-a-subscriber-from-a-ticket.md): Remove a subscriber from an existing ticket. #### TicketTags - [List ticket tags](https://docs.getprimo.com/api-reference/tickettags/list-ticket-tags.md): Return all ticket tags defined for your company. Use their ids to tag a ticket or task. - [Create a ticket tag](https://docs.getprimo.com/api-reference/tickettags/create-a-ticket-tag.md): Create a new ticket tag for your company. - [Delete a ticket tag](https://docs.getprimo.com/api-reference/tickettags/delete-a-ticket-tag.md): Delete a ticket tag. It is removed from every ticket and task that carried it. - [Update a ticket tag](https://docs.getprimo.com/api-reference/tickettags/update-a-ticket-tag.md): Rename an existing ticket tag. #### Softwares - [Get all softwares](https://docs.getprimo.com/api-reference/softwares/get-all-softwares.md): Return the list of software titles managed or distributed by your company (the company-wide catalog) with id, name, platform, source, installation type, and target method. To list the software actually installed on a specific device, use `getDeviceSoftware` instead. `autoUpdatePackage` applies to iO… - [List vulnerabilities](https://docs.getprimo.com/api-reference/softwares/list-vulnerabilities.md): Return the paginated list of CVE vulnerabilities detected across your fleet, with CVSS scores, EPSS probabilities, and host counts. Use `getVulnerability` for one CVE's full details. To list the vulnerable software installed on a single device, use `getDeviceSoftware` with its `vulnerable` filter. - [Get a vulnerability by CVE](https://docs.getprimo.com/api-reference/softwares/get-a-vulnerability-by-cve.md): Return full details for a single CVE vulnerability including affected OS versions and software titles. - [Get a software by ID](https://docs.getprimo.com/api-reference/softwares/get-a-software-by-id.md): Return software details for the given software ID, including targeting details and the install, uninstall and post-install scripts Fleet runs on the device. Use the scripts to diagnose a failed install (see `getSoftwareInstallLogs` for the failure output). The scripts are null for App Store / VPP so… - [Update a software](https://docs.getprimo.com/api-reference/softwares/update-a-software.md): Update ONE software's targeting and settings. Targeting is required: set `targetMethod` to `All` (every device) or `DeviceGroup` with a non-empty `deviceGroupIds`; with `DeviceGroup` you can also pass `excludeDeviceGroupIds` to subtract device groups from the targeted set (devices in an excluded gro… - [Delete a software](https://docs.getprimo.com/api-reference/softwares/delete-a-software.md): Delete ONE software from your company catalog and remove it from the fleet (uninstalling it from targeted devices). This is irreversible. - [List devices targeted by a software](https://docs.getprimo.com/api-reference/softwares/list-devices-targeted-by-a-software.md): Return the paginated list of devices targeted by ONE software, each with its install status and installed version. To list the software on ONE device instead, use `getDeviceSoftware`. - [Sync the company software catalog](https://docs.getprimo.com/api-reference/softwares/sync-the-company-software-catalog.md): Trigger a resync of your company software catalog from the MDM provider (Fleet): refreshes the persisted software list and their per-device install state. Use this after changes made directly in the MDM provider are not yet reflected. To resync ONE device instead, use `syncDeviceSoftware`. - [Simulate a software target count](https://docs.getprimo.com/api-reference/softwares/simulate-a-software-target-count.md): Preview how many devices a given targeting would match (platform + globalTarget or a list of device group IDs), without saving anything. Use this before updating a software’s targeting. - [Get target device counts for softwares](https://docs.getprimo.com/api-reference/softwares/get-target-device-counts-for-softwares.md): Return, for each of the given software IDs, the number of devices currently targeted by that software. To preview a not-yet-saved targeting instead, use `simulateSoftwareTargetCount`. - [Update a software's install scripts](https://docs.getprimo.com/api-reference/softwares/update-a-softwares-install-scripts.md): Replace the install, uninstall and/or post-install script of ONE custom-package software. Send at least one; omitted scripts are left untouched and nothing else changes (targeting, self-service, auto-update, setup experience). Only custom packages qualify — App Store / VPP, Fleet-maintained apps and… - [Get install status counts for softwares](https://docs.getprimo.com/api-reference/softwares/get-install-status-counts-for-softwares.md): Return, for each of the given software IDs, how many devices have it installed, in progress, or failed. Use this for an install-health overview across softwares. #### BillingProfiles - [Get all billing profiles](https://docs.getprimo.com/api-reference/billingprofiles/get-all-billing-profiles.md): Return the company billing profiles. Use an eligible profile id when creating an order. #### AiUsage - [Get the company AI credit usage](https://docs.getprimo.com/api-reference/aiusage/get-the-company-ai-credit-usage.md): Return the AI credits the company has consumed: the period total, a breakdown per feature (credits, metered generations and share of the total, highest spender first) and a per-day series. Defaults to the current UTC calendar month; pass `from` and `to` for another window. The AI usage page in the c… #### Orders - [Get orders, optionally narrowed to one employee or one reference](https://docs.getprimo.com/api-reference/orders/get-orders-optionally-narrowed-to-one-employee-or-one-reference.md): Return the list of orders for your company, most recent first. Pass `employeeId` to read the orders placed for one person instead of paging through the company: stock orders, which carry no employee, are then left out. Pass `reference` to read the one order carrying that reference, stock orders incl… - [Create an order](https://docs.getprimo.com/api-reference/orders/create-an-order.md): Create a catalog order (V2) for your company — stock replenishment, or equipment bought outside an onboarding. To equip a joiner and close the Equipment step of their onboarding, use `executeOnboardingEquipment` instead: this endpoint places the order without touching the onboarding or its ticket. T… - [Get an order by ID](https://docs.getprimo.com/api-reference/orders/get-an-order-by-id.md): Return the order details for the given order ID. - [Get order custom fields](https://docs.getprimo.com/api-reference/orders/get-order-custom-fields.md): Return all Active custom field definitions for the order, each paired with the current stored value (or null when unset). For SELECT / MULTI_SELECT fields the `options` catalog is included so you can map option ids to labels. - [Set an order custom field value](https://docs.getprimo.com/api-reference/orders/set-an-order-custom-field-value.md): Set or overwrite a custom field value on an order. Idempotent. Returns the updated field (definition + value). For SELECT supply the option id (string); for MULTI_SELECT supply an array of option ids. Option ids can be read from the `getOrderCustomFields` endpoint. - [Clear an order custom field value](https://docs.getprimo.com/api-reference/orders/clear-an-order-custom-field-value.md): Remove the stored value for a custom field on an order. Returns the updated field (value reset to null). - [Create an equipment order intent](https://docs.getprimo.com/api-reference/orders/create-an-equipment-order-intent.md): Plan equipment for someone as a task the ticket tracks: a catalog order to place and/or devices and accessories to hand over from stock. Creates the intent and its EQUIPMENT_ORDER task, and places nothing yet — `executeEquipmentOrderIntent` does. Pass the ticket the work belongs to as `parentTicketI… - [Update an equipment order intent](https://docs.getprimo.com/api-reference/orders/update-an-equipment-order-intent.md): Change what an equipment order intent will do before it executes. Only the fields you send change; `order` and `assignedFromInventory` are replaced whole, and null clears one. The employee cannot change: create a new intent for someone else. Refused with `INTENT_ALREADY_EXECUTED` once executed, `TIC… - [Execute an equipment order intent](https://docs.getprimo.com/api-reference/orders/execute-an-equipment-order-intent.md): Carry out an equipment order intent: places its catalog order — a real purchase against its billing profile — hands over its stock items, sends the enrollment request when asked, links the order and devices to its task and completes the task. This is the only way to complete an EQUIPMENT_ORDER task:… #### Saas - [Get all SaaS](https://docs.getprimo.com/api-reference/saas/get-all-saas.md): Return the list of SaaS applications for your company, regardless of their approval status. Each item carries the `id` to pass as `saasId` to the other SaaS endpoints, the application name, its `approvalStatus`, its `connectionStatus`, its tags and how many identities it holds. - [Get the SaaS identities of an employee](https://docs.getprimo.com/api-reference/saas/get-the-saas-identities-of-an-employee.md): Return every SaaS identity held by one employee, across all the SaaS applications of your company — use it to answer whether someone has access to a given application, and with which group, role, license and organization unit. - [Get the SaaS identities no employee owns, across every application](https://docs.getprimo.com/api-reference/saas/get-the-saas-identities-no-employee-owns-across-every-application.md): Return, as a paginated list, the SaaS identities of your company that are linked to no employee and classified as no other kind of account — the identities the cockpit shows as "To link" — across every SaaS application at once, whatever its approval status. Each item carries its `id`, `email`, the `… - [Get a SaaS by ID](https://docs.getprimo.com/api-reference/saas/get-a-saas-by-id.md): Return the SaaS details for the given company SaaS application ID — identities, recent events, contract and provisioning rule. - [Get the issues flagged for a SaaS](https://docs.getprimo.com/api-reference/saas/get-the-issues-flagged-for-a-saas.md): Return the list of provisioning issues currently flagged by the rule on the given SaaS, including missing access, unexpected access, missing/extra group/role/license assignments and orphaned identities. - [Update a SaaS contract](https://docs.getprimo.com/api-reference/saas/update-a-saas-contract.md): Replace the contract configuration for the given SaaS. All prices must be expressed for one billing period defined by `billingFrequency` (not annualized). - [Update a SaaS provisioning rule draft](https://docs.getprimo.com/api-reference/saas/update-a-saas-provisioning-rule-draft.md): Overwrite the draft of the natural-language provisioning rule for this SaaS, and optionally publish it in the same call. You must provide the COMPLETE rule text — this fully replaces the draft, it does not append. Call getSaasById first and re-send the full, edited body. With `publish: true` the new… - [Publish a SaaS provisioning rule](https://docs.getprimo.com/api-reference/saas/publish-a-saas-provisioning-rule.md): Publish the SaaS provisioning rule: copy the current draft to the published text so the agent reads it at runtime when reviewing provisioning for this SaaS. Only call this AFTER the user has reviewed the exact draft in the conversation and explicitly confirmed they want it published — it makes the r… - [Preview the SaaS accounts the rules grant to a person](https://docs.getprimo.com/api-reference/saas/preview-the-saas-accounts-the-rules-grant-to-a-person.md): Judge a person against the company's published SaaS rules and return, for each APPROVED application whose rule grants them an account, the groups, roles, licenses and organization units they should get. The same judgement decides what a new hire is preselected for at onboarding and which access gaps… - [Preview the issues the rule draft of a SaaS raises](https://docs.getprimo.com/api-reference/saas/preview-the-issues-the-rule-draft-of-a-saas-raises.md): Judge the DRAFT of the provisioning rule of the given SaaS — the text the rule editor shows, published or not — against the whole directory, exactly as publishing it would: every employee compared to the account they hold, and every identity on the SaaS. Returns the persons it would flag, with the i… - [Ask for an account to be created on a SaaS application](https://docs.getprimo.com/api-reference/saas/ask-for-an-account-to-be-created-on-a-saas-application.md): Get an employee an account on a SaaS application, with optional group, role, license and organization unit assignments. The account does not exist yet: this endpoint is what brings it into being. - [Create a SaaS account task on a ticket](https://docs.getprimo.com/api-reference/saas/create-a-saas-account-task-on-a-ticket.md): Create, remove or update an employee's account on a SaaS application as a SAAS_PROVISIONING task on a ticket, so the account can be scheduled, cancelled and completed like any task. Pass the untyped ticket the work belongs to, such as an onboarding ticket, as `parentTicketId`; without one Primo open… - [Deprovision a SaaS identity](https://docs.getprimo.com/api-reference/saas/deprovision-a-saas-identity.md): Remove an employee's identity from a SaaS application. - [Reset the password of an employee's identity on a SaaS application](https://docs.getprimo.com/api-reference/saas/reset-the-password-of-an-employees-identity-on-a-saas-application.md): Replace the password of the employee's identity on this SaaS application and mail the new one to them. The password is never returned, so it cannot be repeated in a ticket, a comment or a reply — report only where it was sent. - [Create a SaaS identity directly, with no provisioning ticket](https://docs.getprimo.com/api-reference/saas/create-a-saas-identity-directly-with-no-provisioning-ticket.md): Create the identity record for an account on a SaaS application Primo cannot provision itself, writing it immediately — no provisioning ticket, no task for an admin. Use it when asked to create, add or register an identity, a user or an account on such an application. - [Update the owner of a SaaS](https://docs.getprimo.com/api-reference/saas/update-the-owner-of-a-saas.md): Set the owning employee of the given SaaS application. `ownerId` is the ID of an employee in your company. - [Update the approval status of a SaaS](https://docs.getprimo.com/api-reference/saas/update-the-approval-status-of-a-saas.md): Update the approval status of the given SaaS application. - [Add a SaaS identity to a group](https://docs.getprimo.com/api-reference/saas/add-a-saas-identity-to-a-group.md): Put the account into one of the application's groups. A group whose membership the provider does not let Primo change (a distribution list, a mail-enabled security group, a dynamic-membership group) is rejected with a 409. - [Remove a SaaS identity from a group](https://docs.getprimo.com/api-reference/saas/remove-a-saas-identity-from-a-group.md): Take the account out of one of the application's groups. The account itself is left in place — to remove the account entirely, use `deprovisionSaasIdentity`. - [Give a SaaS identity a role](https://docs.getprimo.com/api-reference/saas/give-a-saas-identity-a-role.md): Give the account one of the application's roles. - [Take a role off a SaaS identity](https://docs.getprimo.com/api-reference/saas/take-a-role-off-a-saas-identity.md): Take one of the application's roles off the account. The account itself is left in place — to remove the account entirely, use `deprovisionSaasIdentity`. - [Give a SaaS identity a licence](https://docs.getprimo.com/api-reference/saas/give-a-saas-identity-a-licence.md): Give the account one of the application's licences. A licence is a billed seat: read `contract.licenses[].pricePerSeat` on `getSaasById` for what it costs per billing period before asking for it. - [Take a licence off a SaaS identity](https://docs.getprimo.com/api-reference/saas/take-a-licence-off-a-saas-identity.md): Take one of the application's licences off the account. The account itself is left in place, and keeps whatever else it holds — to remove the account entirely, use `deprovisionSaasIdentity`. - [Put a SaaS identity in an organization unit](https://docs.getprimo.com/api-reference/saas/put-a-saas-identity-in-an-organization-unit.md): Put the account in one of the application's organization units. - [Take a SaaS identity out of an organization unit](https://docs.getprimo.com/api-reference/saas/take-a-saas-identity-out-of-an-organization-unit.md): Take the account out of one of the application's organization units. The account itself is left in place — to remove the account entirely, use `deprovisionSaasIdentity`. - [Add a license to a SaaS](https://docs.getprimo.com/api-reference/saas/add-a-license-to-a-saas.md): Add a new license to the SaaS catalog. Only allowed when the SaaS license capability is set to MANUAL (i.e. a manually-provisioned SaaS). Returns 409 otherwise. - [Rename a license of a SaaS](https://docs.getprimo.com/api-reference/saas/rename-a-license-of-a-saas.md): Rename an existing license. `remoteId` is the entitlement ID returned by `getSaasById`. Only allowed when the SaaS license capability is set to MANUAL (i.e. a manually-provisioned SaaS). Returns 409 otherwise. - [Remove a license from a SaaS](https://docs.getprimo.com/api-reference/saas/remove-a-license-from-a-saas.md): Remove an existing license. `remoteId` is the entitlement ID returned by `getSaasById`. Only allowed when the SaaS license capability is set to MANUAL (i.e. a manually-provisioned SaaS). Returns 409 otherwise. - [Add a role to a SaaS](https://docs.getprimo.com/api-reference/saas/add-a-role-to-a-saas.md): Add a new role to the SaaS catalog. Only allowed when the SaaS role capability is set to MANUAL (i.e. a manually-provisioned SaaS). Returns 409 otherwise. - [Rename a role of a SaaS](https://docs.getprimo.com/api-reference/saas/rename-a-role-of-a-saas.md): Rename an existing role. `remoteId` is the entitlement ID returned by `getSaasById`. Only allowed when the SaaS role capability is set to MANUAL (i.e. a manually-provisioned SaaS). Returns 409 otherwise. - [Remove a role from a SaaS](https://docs.getprimo.com/api-reference/saas/remove-a-role-from-a-saas.md): Remove an existing role. `remoteId` is the entitlement ID returned by `getSaasById`. Only allowed when the SaaS role capability is set to MANUAL (i.e. a manually-provisioned SaaS). Returns 409 otherwise. - [Add a group to a SaaS](https://docs.getprimo.com/api-reference/saas/add-a-group-to-a-saas.md): Add a new group to the SaaS catalog. Only allowed when the SaaS group capability is set to MANUAL (i.e. a manually-provisioned SaaS). Returns 409 otherwise. - [Rename a group of a SaaS](https://docs.getprimo.com/api-reference/saas/rename-a-group-of-a-saas.md): Rename an existing group. `remoteId` is the entitlement ID returned by `getSaasById`. Only allowed when the SaaS group capability is set to MANUAL (i.e. a manually-provisioned SaaS). Returns 409 otherwise. - [Remove a group from a SaaS](https://docs.getprimo.com/api-reference/saas/remove-a-group-from-a-saas.md): Remove an existing group. `remoteId` is the entitlement ID returned by `getSaasById`. Only allowed when the SaaS group capability is set to MANUAL (i.e. a manually-provisioned SaaS). Returns 409 otherwise. - [Add an organization unit to a SaaS](https://docs.getprimo.com/api-reference/saas/add-an-organization-unit-to-a-saas.md): Add a new organization unit to the SaaS catalog. Only allowed when the SaaS organization unit capability is set to MANUAL (i.e. a manually-provisioned SaaS). Returns 409 otherwise. - [Rename an organization unit of a SaaS](https://docs.getprimo.com/api-reference/saas/rename-an-organization-unit-of-a-saas.md): Rename an existing organization unit. `remoteId` is the entitlement ID returned by `getSaasById`. Only allowed when the SaaS organization unit capability is set to MANUAL (i.e. a manually-provisioned SaaS). Returns 409 otherwise. - [Remove an organization unit from a SaaS](https://docs.getprimo.com/api-reference/saas/remove-an-organization-unit-from-a-saas.md): Remove an existing organization unit. `remoteId` is the entitlement ID returned by `getSaasById`. Only allowed when the SaaS organization unit capability is set to MANUAL (i.e. a manually-provisioned SaaS). Returns 409 otherwise. - [Archive a SaaS application user](https://docs.getprimo.com/api-reference/saas/archive-a-saas-application-user.md): Archive (soft-delete) a SaaS application user. The user is removed from active listings but kept for historical reporting. - [Permanently delete a SaaS application user](https://docs.getprimo.com/api-reference/saas/permanently-delete-a-saas-application-user.md): Permanently delete a SaaS application user and its activity history. This is irreversible — prefer `archiveSaasApplicationUser` unless a hard delete is required. - [Archive several SaaS application users](https://docs.getprimo.com/api-reference/saas/archive-several-saas-application-users.md): Archive (soft-delete) MULTIPLE SaaS application users in one call — the batch form of `archiveSaasApplicationUser`, with the same rules per identity. The users are removed from active listings but kept for historical reporting. - [Permanently delete several SaaS application users](https://docs.getprimo.com/api-reference/saas/permanently-delete-several-saas-application-users.md): Permanently delete MULTIPLE SaaS application users and their activity history — the batch form of `deleteSaasApplicationUser`. This is irreversible for every item that succeeds: prefer `archiveSaasApplicationUsers` unless a hard delete is required. - [Create several SaaS identities directly, with no provisioning ticket](https://docs.getprimo.com/api-reference/saas/create-several-saas-identities-directly-with-no-provisioning-ticket.md): Record MULTIPLE accounts on a SaaS application Primo cannot provision itself — the batch form of `createSaasIdentity`, with the same rules per item. Use it to onboard a list of employees onto a manually-managed application in one call. #### Catalog - [List catalog countries](https://docs.getprimo.com/api-reference/catalog/list-catalog-countries.md): Return the list of catalog country codes available to your company. - [Search catalog products](https://docs.getprimo.com/api-reference/catalog/search-catalog-products.md): Search the product catalog for a given country. Filter deterministically by product type, brand, zero-touch deployment support, stock availability, and by specification via `specifications`. ram, storage (GB amounts), screenSize (whole inches), processor (`BRAND|Family`) and keyboardLayout (layout c… - [Get catalog filter options](https://docs.getprimo.com/api-reference/catalog/get-catalog-filter-options.md): Return every distinct filter value the catalog holds for a country, optionally narrowed to specific product types: brands plus the ram, storage, screenSize, processor, operatingSystem, resolution, position and keyboardLayout specification values. ram, storage and screenSize are canonical numbers (GB… - [Get a catalog product](https://docs.getprimo.com/api-reference/catalog/get-a-catalog-product.md): Return the full details of a catalog product for a country, including its variants and per-supplier stock information. - [List shipping countries](https://docs.getprimo.com/api-reference/catalog/list-shipping-countries.md): Return your company's shipping countries with their enablement status. - [List company addresses for a shipping country](https://docs.getprimo.com/api-reference/catalog/list-company-addresses-for-a-shipping-country.md): Return the company's saved addresses in the given shipping country. Use one of these as the shipping address when creating an order. - [List the catalog favorites of a country](https://docs.getprimo.com/api-reference/catalog/list-the-catalog-favorites-of-a-country.md): Return the products an admin has pinned as favorites for one country, split into devices and accessories and carrying the full product details — the same shape searchCatalogProducts returns. Favorites lead the catalog listing in the cockpit and are curated by hand, so this is the deterministic answe… - [Pin a catalog product as a favorite](https://docs.getprimo.com/api-reference/catalog/pin-a-catalog-product-as-a-favorite.md): Mark one catalog product as a favorite for one country, so it leads the catalog listing for everyone in the company. Idempotent — pinning an already-favorite product changes nothing. Answers with the refreshed favorites of that country. Fails with 404 when the product is not sold in that country; ca… - [Unpin a catalog product from the favorites](https://docs.getprimo.com/api-reference/catalog/unpin-a-catalog-product-from-the-favorites.md): Remove one catalog product from the favorites of one country, so it stops leading the catalog listing. Idempotent — unpinning a product that is not a favorite changes nothing and still answers with the refreshed favorites of that country. This affects what the whole company sees in the catalog, so c… #### Shipments - [Get shipments, optionally narrowed to one employee](https://docs.getprimo.com/api-reference/shipments/get-shipments-optionally-narrowed-to-one-employee.md): Return the list of shipments for your company, most recent first. Pass `employeeId` to read the shipments of one person instead of paging through the company. Only an offboarding shipment carries an employee, so every other shipment is then left out. Resolve a name to an id with `getEmployees` first… - [Create a shipment](https://docs.getprimo.com/api-reference/shipments/create-a-shipment.md): Create a new shipment for your company. - [Get a shipment by ID](https://docs.getprimo.com/api-reference/shipments/get-a-shipment-by-id.md): Return the shipment details for the given shipment ID. #### KnowledgeBaseItems - [List the company knowledge base items](https://docs.getprimo.com/api-reference/knowledgebaseitems/list-the-company-knowledge-base-items.md): List every knowledge base item (e.g. Skills — reusable instruction packages) owned by the company, with their draft, published text and publication status. Call this to find an item's id before reading, editing or publishing it. Does not include the Equipment or Purchasing policy — use their dedicat… - [Get a knowledge base item](https://docs.getprimo.com/api-reference/knowledgebaseitems/get-a-knowledge-base-item.md): Return a single knowledge base item by id: its editable draft, the published text the agent sees at runtime (or null if never published), and its publication status. Read this before updating so you can show the user the current text. #### Onboardings - [Get all onboardings](https://docs.getprimo.com/api-reference/onboardings/get-all-onboardings.md): Return the list of employee onboardings for your company. - [Create an onboarding for an existing employee](https://docs.getprimo.com/api-reference/onboardings/create-an-onboarding-for-an-existing-employee.md): Start the onboarding of an employee who already exists in Primo: creates the onboarding, its ticket and the "Confirm onboarding information" task, then the admins run the email, SaaS provisioning and equipment steps from the cockpit according to the onboarding settings. The employee must exist first… - [Get the onboarding settings](https://docs.getprimo.com/api-reference/onboardings/get-the-onboarding-settings.md): Return the company onboarding settings: which steps (email, SaaS provisioning, equipment) every onboarding includes, who owns each of them and when they are due, the scheduling of each step, the default ticket owner, priority and subscribers, whether the Primo AI agent is put on onboarding tickets o… - [Update the onboarding settings](https://docs.getprimo.com/api-reference/onboardings/update-the-onboarding-settings.md): Change the company onboarding settings — the steps every onboarding includes, their owners, due dates and scheduling, the default ticket owner, priority and subscribers, the Primo AI agent options, and when a hire detected in the HRIS gets its onboarding ticket (`onboardingTicketCreation`). Only the… - [Get an onboarding by ID](https://docs.getprimo.com/api-reference/onboardings/get-an-onboarding-by-id.md): Return the onboarding details for the given onboarding ID. - [Complete onboardings in bulk](https://docs.getprimo.com/api-reference/onboardings/complete-onboardings-in-bulk.md): Close many onboardings for employees already in post in one call. Each one creates the employee from the connected HRIS data if needed and marks the employee active, without executing the remaining onboarding actions (no equipment ordered, no SaaS provisioned). Best-effort and independent: the call… - [Complete an onboarding](https://docs.getprimo.com/api-reference/onboardings/complete-an-onboarding.md): Close an onboarding for an employee already in post: creates the employee from the connected HRIS data if needed and marks the employee active, without executing the remaining onboarding actions (no equipment ordered, no SaaS provisioned). - [Ignore onboardings in bulk](https://docs.getprimo.com/api-reference/onboardings/ignore-onboardings-in-bulk.md): Discard many pending onboardings in one call — cancels each without creating the employee. Best-effort and independent: the call returns 200 with a per-id `results` manifest (`ok` / `error`) — always inspect `results` rather than the HTTP status to detect partial failures. Up to 10 ids per call. - [Ignore an onboarding](https://docs.getprimo.com/api-reference/onboardings/ignore-an-onboarding.md): Discard a pending onboarding: cancels it without creating the employee (the opposite of completeOnboarding, which keeps the employee active). Only pending onboardings can be ignored. - [Execute the equipment step of an onboarding](https://docs.getprimo.com/api-reference/onboardings/execute-the-equipment-step-of-an-onboarding.md): Equip a joiner and close the Equipment step of their onboarding in one call: places the catalog order when `order` is provided, assigns devices and accessories from existing stock when `assignedFromInventory` is provided, then moves the step and its onboarding-ticket task to done and links the order… - [Create an email account intent](https://docs.getprimo.com/api-reference/onboardings/create-an-email-account-intent.md): Ask for an employee's professional mailbox at the company's email provider as a task a ticket tracks. Creates the intent and its EMAIL_ACCOUNT task. Without `scheduleDate` the mailbox is created right away; with one, the task sleeps until that date and the mailbox is created when it wakes up — nobod… - [Update an email account intent](https://docs.getprimo.com/api-reference/onboardings/update-an-email-account-intent.md): Change the credentials recipient, the personal email or the groups, roles, licenses and organization units of an email account intent before its mailbox is created — typically while its task sleeps until its date. Only the fields you send change; a resource list is replaced whole. The employee canno… - [Execute an email account intent](https://docs.getprimo.com/api-reference/onboardings/execute-an-email-account-intent.md): Create the intent's mailbox at the email provider now and complete its task. Rarely needed: the mailbox is created on its own when the task is created without a date or wakes up on its date. Use it to retry after a refusal left the task PENDING with a comment. This is the only way to complete an EMA… - [Create an employee creation intent](https://docs.getprimo.com/api-reference/onboardings/create-an-employee-creation-intent.md): Create the employee of an onboarding as a task the ticket tracks, from the HR information (name, emails, phone, start date, job, legal entity, work location, teams, manager, address). Creates the intent and its EMPLOYEE_CREATION task. Without `scheduleDate` the employee is created right away — a rea… - [Update an employee creation intent](https://docs.getprimo.com/api-reference/onboardings/update-an-employee-creation-intent.md): Change the HR information an employee creation intent will create the employee from, before it executes — typically while its task sleeps until its date, or after a refusal left it PENDING. Only the fields you send change (`teams` is replaced whole); null clears one. The onboarding cannot change: cr… - [Execute an employee creation intent](https://docs.getprimo.com/api-reference/onboardings/execute-an-employee-creation-intent.md): Carry out an employee creation intent: creates the employee (or updates the one the onboarding already holds) from the intent, links them to the onboarding, cancels a leftover offboarding, adds them to the company in Clerk — a real user account — links the employee to its task and completes the task… #### Offboardings - [Get all offboardings](https://docs.getprimo.com/api-reference/offboardings/get-all-offboardings.md): Return the list of employee offboardings for your company. - [Get an offboarding by ID](https://docs.getprimo.com/api-reference/offboardings/get-an-offboarding-by-id.md): Return the offboarding details for the given offboarding ID. ## OpenAPI Specs - [openapi](https://api.getprimo.com/openapi.json)