Technical Implementation Guide

Audience: Engineers integrating with the Assessments APIs, automating assessment creation, or configuring entity-trigger question mappings.

This guide covers the Assessment Workflow API, how to reach it as an MCP tool instead of raw REST calls, the newer assessment listing/reporting endpoints, and the markup rules for question/section description fields. For the full interactive reference (every field, every response shape, and a request builder), see Privacy Assessments in the API Reference.

#Authentication and base URLs

Every request needs an Authorization: Bearer <token> header carrying an access token issued by the Relyance Identity Service. A token is scoped to one workspace, and every response is limited to that workspace's data.

Errors use RFC 9457 problem documents (application/problem+json) with title, status, detail, and a machine-readable code - the same shape across every endpoint below.

#Assessment Workflow API

Triggers a published workflow made up of one or more steps - typically CREATE_VENDOR, CREATE_ASSESSMENT, and SHARE_ASSESSMENT - and lets you poll the result. This is the API-driven equivalent of an admin manually creating a vendor, creating an assessment against it, and sharing it with stakeholders, collapsed into one call plus a status check - a common shape for a security team automating vendor intake: a new vendor shows up in procurement, and this single call creates the vendor record, generates the scoped security assessment, and sends it to the vendor's security contact, all before anyone on the team has to open the platform.

#Trigger a workflow

POST /api/privacy/workflow/v1/trigger

The only structurally required field is workflowId - the workflow must already exist and be published. Which other fields are required depends on the steps that workflow contains:

{
  "workflowId": "68fb2683a470efb68c49c34f",
  "vendorName": "Acme Analytics",
  "vendorUrl": "https://acme-analytics.example.com",
  "vendorDescription": "Product analytics vendor",
  "stakeholderEmails": ["security@acme-analytics.example.com"]
}

A successful call returns 202 Accepted with a transactionId - the workflow runs asynchronously, so this response confirms the run started, not that it finished.

#Poll workflow status

GET /api/privacy/workflow/v1/{transaction_id}

Returns the workflow's name, description, overall workflowStatus (COMPLETED, EXECUTING, FAILED), and a steps array - each step's name, status, execution timestamp, log messages, and response values (for example, the created vendor's key or the new assessment's ID and URL). Use this to confirm a workflow finished, pull the assessment URL it produced, or diagnose exactly which step failed and why.

#Trigger a workflow (v2)

POST /api/privacy/workflow/v2/trigger

A more general version of the same endpoint: it stores the raw request body as-is, and each workflow step's own fieldsMapping (a Jinja template) picks out whatever fields it needs via {{ payload.X }} paths at execution time. Only workflowId is structurally required - everything else in the body is opaque to this API and interpreted entirely by the workflow's own step configuration, so the same endpoint can back a wide variety of workflow shapes without a schema change. Poll its status with the same GET /api/privacy/workflow/v1/{transaction_id} endpoint above.

Building the workflow itself (naming its steps, wiring fieldsMapping templates, and publishing it) happens in your Relyance workspace's workflow configuration - if you don't already have a workflowId to trigger, contact your account team.

#Calling it as an MCP tool instead of REST

The Assessment Workflow API is also reachable as a set of MCP (Model Context Protocol) tools, not just plain REST - useful if you're wiring an AI agent up to create vendors, create assessments, and share them conversationally, rather than hand-writing HTTP calls. The service publishes a /.well-known/mcp discovery document that an MCP-compatible gateway or client reads to find its tools automatically; today that surface exposes the same three operations described above, one-to-one:

Authentication and request/response shapes are identical either way - MCP is an additional transport onto the same endpoints, not a separate API surface with its own rules. A broader set of tools (searching existing assessments, fetching full assessment detail, updating fields on one, and aggregate reporting) is in development; check back or ask your account team if you need more than trigger/status today.

#Assessment Listing & Reporting API

#Read a single assessment

GET /api/privacy/assessment/v1/{form_id}
PUT /api/privacy/assessment/v1/{form_id}
GET /api/privacy/assessment/v1/{form_id}/entities

GET returns the full assessment by its form ID; PUT updates its answers; the /entities route returns the entities (vendor, processing activity, AI model, and so on) the assessment is linked to. Same Authorization: Bearer <token> auth as every other endpoint on this API.

#List and report on assessments across your tenant

The same data that powers the Assessments dashboard's Volume and Avg Processing Time widgets (see Assessment Audit Log and Reporting) is also reaching the Privacy API as its own endpoints:

• A list endpoint (GET /api/privacy/assessments/v1) returning each assessment's status, template/type, and created/completed timestamps, with basic filtering and pagination (by date range, status, and type).
• A metrics endpoint (GET /api/privacy/assessments/v1/metrics) returning the same monthly rollup the dashboard shows: created and completed counts, median and p90 days from creation to completion, and SLA attainment percent, for a requested date range.

This shipped very recently. See Assessment Listing & Reporting in the API Reference for the full field-by-field schema and a request builder for every endpoint in this section.

#Question types and entity-trigger mapping

Assessment templates support several question types - free text, single/multi-select, and matrix (grid) questions. Matrix questions can additionally be configured as entity triggers: mapping specific cells or rows to downstream entity logic, rather than existing purely as a static grid of answers. Configure this from the template editor; see the Admin Configuration Guide for where that lives in the UI.

#Question and section descriptions: rich text and the HTML source editor

Question description and section description fields use a rich-text (Quill) editor with an additional </> source-mode toggle in the formatting toolbar, for anyone who needs markup the visual editor can't easily produce - code blocks, specific link attributes, or nested lists pasted from another tool.

• Click </> to switch the field to a raw HTML textarea; click it again to return to the visual editor, which normalizes the HTML so the rendered output matches what you typed.
• On the way back to visual mode, content passes through Quill and a DOMPurify sanitization pass. Standard formatting tags (<p>, <ul>, <ol>, <li>, <strong>, <em>, <u>, <a>, <div>, and Quill's code-block containers) are fully supported; anything unsafe is stripped automatically, and malformed tags are corrected rather than rejected outright.
• Scope is deliberately narrow. The </> toggle exists only on assessment question and section description fields - not on question titles, answer fields, assessment comments, DSR editors, Insights editors, or workflow task editors. It's opt-in per editor component, so nothing changes for any other Quill-based field in the platform.
• Existing descriptions are unaffected until you actually edit them in source mode - opening </> on a description someone already wrote just shows you the HTML the visual editor already generated.

#Troubleshooting

• An assessment distributed via a generic shareable link doesn't map back to an entity - entity association for generic-link assessments (as opposed to assessments created directly against a specific vendor, processing activity, AI model, or AI use case) is still rolling out. Until it's confirmed available on your account, point stakeholders at an entity-specific assessment link rather than a generic one if you need Attestations to work reliably.
• Shared/restricted assessment access isn't matching an invited stakeholder's email - email matching for restricted, shared assessments is case-insensitive; if access still fails, confirm the exact address on the invite rather than assuming a casing issue.
• An assessment won't move to Complete - some assessment types (for example, those requiring a Data Processing Agreement) gate completion behind that document's upload; check for an outstanding prerequisite before assuming a bug.

#Related reading

• API Reference - the full interactive reference for the Assessment Workflow and Assessment Listing & Reporting APIs, generated from the same OpenAPI description these endpoints are documented from
• Admin Configuration Guide - building templates and configuring how assessments get created in the platform UI
• Legal and Compliance Guide - the compliance rationale behind the audit log, drift notifications, and Attestations