Assessments, results and reports

Vocabulary

Term	Meaning	Catalog
Assessment library	An assessment product, for example Core Drivers or Core Values. What a person takes.	GET /assessment_libraries
Assigned assessment	One person's instance of an assessment library, with a status and scores.	GET /users/{user_id}/assessments
Report (user report library)	A presentation of results, for example Core Drivers Pro. A report requires one or more assessment libraries.	GET /reports
Assigned user report	A report made visible to one person.	GET /users/{user_id}/reports

A person can have completed an assessment without seeing any report, and the API can download a report even when the person cannot see it.

Assigning assessments

Campaigns are the usual way to assign assessments (see Campaigns). To manage a single person directly:

Endpoint	Purpose
GET /users/{user_id}/assessments	Every assessment the person has, with status, started_at, finished_at, retake and score_type.
PUT /users/{user_id}/assessments/{assessment_library_id}	Assign the assessment. 201 when assigned, 200 when they already had it. The body is the assignment outcome: changed, skipped and outcomes with one entry { "userId", "reason" } whose reason is assigned or already_assigned.
DELETE /users/{user_id}/assessments/{assessment_library_id}	Unassign an assessment that has not been completed.

Assigning this way does not send an e-mail. Send the person to the platform through SSO or tell them to sign in.

Reading results

GET /users/{user_id}/results returns the user with every completed assessment and its scales:

{
  "user": { "user_id": 28663, "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com", "groups": ["sales"], "locale": "en" },
  "userAssignedAssessments": [
    {
      "assessment": {
        "name": "Core Drivers", "id": 49344, "assessment_library_id": 24, "score_type": "core_drivers_leadership",
        "reports": [ { "assigned_user_report": { "id": 33005, "userReportName": "Core Drivers Pro" } } ]
      },
      "scales": { "Drive": 74.83, "Drive//Leading": 72.54, "Openness": 38.26 }
    }
  ]
}

Scales are the same as in the AssignedAssessmentFinished webhook and differ per assessment. For account-level competency models, GET /users/{user_id}/competency-score returns each competency's score keyed by its identifier.

For many users at once, use a table query with score columns.

Report visibility

Whether a person can open a report on the platform is a per-person switch, the same one administrators toggle in the admin app.

Endpoint	Purpose
GET /users/{user_id}/reports	Every report available on the account for this person, with visible, ready and pending_assessment_library_ids.
GET /users/{user_id}/reports/{user_report_library_id}	One report's state.
PUT /users/{user_id}/reports/{user_report_library_id}	Make it visible. 201 switched on, 200 already visible. A report built on one assessment needs that assessment assigned to the person first: otherwise 404 with trans_code: exception.assignedAssessment.notFound, and nothing changes.
DELETE /users/{user_id}/reports/{user_report_library_id}	Hide it again. The person's results are untouched.

Assign the assessment first (PUT /users/{user_id}/assessments/{assessment_library_id}), then switch on its report. Reports that combine several assessments can be switched on at any time. ready: false means the person has not completed every assessment the report needs; the report shows as pending on the platform until they do. Reports with default_assign: true in GET /reports become visible automatically when assigned through a campaign or playbook.

Downloading PDFs

Endpoint	Notes
GET /pdf/v2/user/{user_id}/report/{user_report_library_id}/download/{locale}	Preferred. Works whether or not the report is visible to the person. 409 with trans_code: exception.report.notReady and data.pending_assessment_library_ids when assessments are missing.
GET /pdf/v2/user-report/{assigned_user_report_id}/download/{locale}	By assigned-report id (from GET /users/{user_id}/results or the webhook). Only for visible reports.
GET /pdf/v2/user/{user_id}/{assessment_library_id}/download/{locale}	By assessment library; resolves the assessment's main report. Only for visible reports.
GET /pdf/team/{team_id}/report/{user_report_library_id}/locale/{locale}/download	Team report.

Responses stream application/pdf. Rendering takes a few seconds; set client timeouts accordingly.

curl -o jane-core-drivers.pdf \
  "https://api.deepersignals.com/api/external/pdf/v2/user/28663/report/6/download/en" \
  -H "X-TOKEN: $DS_API_TOKEN"

Share links

A share link opens a report in the browser without signing in. Both endpoints return a token and the full url:

	Body
POST /share/v2/token/user-report/{locale}	{ "assigned_user_report": 33005 }
POST /share/v2/token/user/assessment-report/{locale}	{ "user": 28663, "assessment_library": 24 }

{ "token": "676e6f35cfc1...", "url": "https://app.deepersignals.com/examplecorp/share/676e6f35cfc1...", "locale": "en" }

Team reports: GET /share/token/team/{team_id}/report/{user_report_library_id}/locale/{locale}.

A request without the required id answers 422 naming it, for example assigned_user_report is required.

Share links do not expire and are not personal; anyone with the URL can open the report.

Teams

Teams group a manager with members for team reports:

• POST /team, PUT /team/{team_id}, DELETE /team/{team_id} with name, manager (user id), members (user ids) and the visibility flags visible_to_member, visible_to_manager, show_results.
• POST /team/table and POST /team/{team_id}/members/table are table queries; GET /team/columns lists their columns.
• GET /team/{team_id}/scores returns the aggregated team scales (for example team_drive, manager_and_team_drive).