> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getprimo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Preview the SaaS accounts the rules grant to a person
> 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 an application shows.
The person is described by attributes, not by an id: they do not need to exist in Primo yet, so it answers for a future hire as well as for an employee. For an existing employee, pass what `getEmployee` and `getEmployeeCustomFields` return for them — the rules may depend on any of it, custom fields included.
It creates nothing. Each entry carries the `saasId` and the entitlement ids `provisionSaasIdentity` takes, so a proposal built from it can be carried out once approved. An application without a published rule, or whose rule does not grant the person, is absent.
EXPENSIVE: one AI judgement per application with a published rule. Call it once per person, never in a loop or across the directory.
Key: ReadScope: Company
## OpenAPI
````yaml https://api.getprimo.com/openapi.json post /saas/identities/preview
openapi: 3.1.1
info:
title: Public API - BETA
description: Read docs on https://docs.getprimo.com/
version: '1.0'
contact: {}
servers:
- url: https://api.getprimo.com
security:
- apikey: []
tags: []
paths:
/saas/identities/preview:
post:
tags:
- Saas
summary: Preview the SaaS accounts the rules grant to a person
description: >-
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 an application shows.
The person is described by attributes, not by an id: they do not need to
exist in Primo yet, so it answers for a future hire as well as for an
employee. For an existing employee, pass what `getEmployee` and
`getEmployeeCustomFields` return for them — the rules may depend on any
of it, custom fields included.
It creates nothing. Each entry carries the `saasId` and the entitlement
ids `provisionSaasIdentity` takes, so a proposal built from it can be
carried out once approved. An application without a published rule, or
whose rule does not grant the person, is absent.
EXPENSIVE: one AI judgement per application with a published rule. Call
it once per person, never in a loop or across the directory.
operationId: previewSaasIdentitiesFromRules
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PreviewSaasIdentitiesBody'
responses:
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PreviewSaasIdentities_Output'
components:
schemas:
PreviewSaasIdentitiesBody:
type: object
properties:
firstName:
description: First name of the person.
type: string
minLength: 1
lastName:
description: Last name of the person.
type: string
minLength: 1
email:
description: Work email of the person.
type: string
minLength: 1
teams:
description: >-
Names of the teams the person is in, as the company writes them. A
team that does not exist in Primo yet is fine.
type: array
items:
type: string
minLength: 1
jobs:
description: >-
Job titles of the person. A title that does not exist in Primo yet
is fine.
type: array
items:
type: string
minLength: 1
workLocation:
description: Name of the work location, e.g. an office or a city.
type: string
minLength: 1
legalEntity:
description: Name of the legal entity that employs the person.
type: string
minLength: 1
managerFullName:
description: Full name of the person's manager.
type: string
minLength: 1
employmentType:
description: Kind of contract, e.g. permanent, contractor, intern.
type: string
minLength: 1
customFields:
description: >-
The person's employee custom field values. The rules read them by
the field's label.
type: array
items:
type: object
properties:
customFieldId:
description: >-
Id of an active employee custom field, as listed by
`getEmployeeCustomFields` → `field.id`.
type: string
minLength: 1
value:
description: >-
Value in the same shape `setEmployeeCustomFieldValue` takes:
an option id for SELECT, an array of option ids for
MULTI_SELECT, a boolean for CHECKBOX, a number for NUMBER, a
string otherwise.
anyOf:
- type: boolean
- type: number
- type: string
- type: array
items:
type: string
required:
- customFieldId
- value
PreviewSaasIdentities_Output:
type: object
properties:
data:
type: array
description: >-
One entry per APPROVED application whose published rule grants the
person an account. An application the rules do not grant is absent.
items:
type: object
properties:
saasId:
description: >-
The company SaaS application ID. Pass it as `saasId` to
`provisionSaasIdentity` or `getSaasById`. This is NOT the
global catalog saasApplicationId.
type: string
saasName:
description: Name of the SaaS application.
anyOf:
- type: string
- type: 'null'
groups:
description: Groups the rule grants.
type: array
items:
type: object
properties:
id:
description: >-
Identifier of this entitlement in the SaaS application —
the same value `provisionSaasIdentity` expects in its
`groups`, `roles`, `licenses` and `organizationUnits`
arrays.
type: string
name:
description: Human-readable entitlement name.
type: string
required:
- id
- name
additionalProperties: false
roles:
description: Roles the rule grants.
type: array
items:
type: object
properties:
id:
description: >-
Identifier of this entitlement in the SaaS application —
the same value `provisionSaasIdentity` expects in its
`groups`, `roles`, `licenses` and `organizationUnits`
arrays.
type: string
name:
description: Human-readable entitlement name.
type: string
required:
- id
- name
additionalProperties: false
licenses:
description: >-
Licenses the rule grants. A licence is a billed seat: its
price is on `getSaasById` → `contract`.
type: array
items:
type: object
properties:
id:
description: >-
Identifier of this entitlement in the SaaS application —
the same value `provisionSaasIdentity` expects in its
`groups`, `roles`, `licenses` and `organizationUnits`
arrays.
type: string
name:
description: Human-readable entitlement name.
type: string
required:
- id
- name
additionalProperties: false
organizationUnits:
description: Organization units the rule grants.
type: array
items:
type: object
properties:
id:
description: >-
Identifier of this entitlement in the SaaS application —
the same value `provisionSaasIdentity` expects in its
`groups`, `roles`, `licenses` and `organizationUnits`
arrays.
type: string
name:
description: Human-readable entitlement name.
type: string
required:
- id
- name
additionalProperties: false
required:
- saasId
- saasName
- groups
- roles
- licenses
- organizationUnits
additionalProperties: false
required:
- data
additionalProperties: false
securitySchemes:
apikey:
scheme: bearer
bearerFormat: API key
type: http
description: >-
Use your Primo API key in the Authorization header as `Bearer
`.
````