Skip to main content

Playbooks

A playbook bundles what should happen to a user right after they sign in or are created through single sign-on: which assessments they get, which reports they may see, and which groups and projects they join.

You create a playbook once and reuse it for every user. That means no API call per user: sign the SSO JWT with the playbook's identity (or set it as the SAML relay state) and the user is created and set up in one step.

Fields​

FieldDescription
nameLabel shown in the admin app.
assessment_librariesIds of the assessments to assign. Required. Catalog: GET /assessment_libraries.
user_report_librariesIds of the reports to make visible for those assessments. Catalog: GET /reports.
groupsGroup ids the user joins.
projectsIds of projects the user joins. Project ids are shown in the admin app.
default_for_loginWhen true, this playbook also runs for users who sign in through SAML without a relay state or playbook URL.
identityGenerated on creation. The value you reference from SSO.

Using the API​

  • GET /playbook lists the account's playbooks with their identity.
  • POST /playbook/create creates one.
  • PUT /playbook/{playbook_id} and DELETE /playbook/{playbook_id} update and remove it.
curl -X POST https://api.deepersignals.com/api/external/playbook/create \
  -H "X-TOKEN: $DS_API_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "New hires 2026",
    "assessment_libraries": [24],
    "user_report_libraries": [6],
    "groups": [135],
    "projects": [1],
    "default_for_login": false
  }'

The response carries the generated identity:

{
  "id": 4,
  "name": "New hires 2026",
  "identity": "60ae0168f2eb7",
  "assessment_libraries": [{ "id": 24, "name": "Core Drivers" }],
  "user_report_libraries": [{ "id": 6, "name": "Core Drivers Pro" }],
  "usergroups": [{ "id": 135, "name": "Sales" }],
  "projects": [{ "id": 1, "name": "Onboarding" }],
  "default_for_login": false,
  "account": { "id": 1, "name": "Example Corp", "index_name": "examplecorp" }
}

Using the identity​

Sign-in methodWhere the identity goes
JWT SSOidentity claim of the token.
SAML, IdP-initiatedThe playbook's relay state code configured in your IdP.
SAML, SP-initiatedThe playbook's Playbook URL, distributed to the users who should get it.

A playbook only adds. Running it again for a user who already has the assessment does not assign a duplicate.