API Reference

Principal API

Principal operations for submitting and tracking review jobs

Endpoints in this group

POST/v1/principal/jobsSubmit a document for review
GET/v1/principal/jobsList review jobs with pagination
GET/v1/principal/jobs/{id}Get review job details with anonymised review actions

POST/v1/principal/jobs

Submit a document for review

Request body

Field	Type	Req	Description
`documentUrl`	string (uri)	Yes	URL to download the document
`documentType`	string	Yes	Type of document (e.g. SUITABILITY_REPORT)
`clientReference`	string	Yes	Client reference identifier
`documentReference`	string	Yes	Document reference identifier
`factFindSummary`	object	Yes	Summary of the client fact find
`priority`	string	No	Job priority level `STANDARDURGENT`
`modelProvider`	string	No	AI model provider that produced the advice (e.g. "openai", "anthropic"). Required for inclusion in the model registry and drift detection.
`modelVersion`	string	No	Specific model version that produced the advice. Pinning the exact version (rather than a moving alias) is what makes drift detection meaningful.
`modelConfiguration`	object	No	Inference parameters used for this generation (temperature, top_p, system prompt hash, etc.). Stored verbatim with the record so audits can reproduce the conditions.
`vulnerabilityFlags`	string[]	No	FCA FG21/1 vulnerability drivers identified on the underlying client. Any non-empty value forces `requiresSeniorSignOff: true` and restricts routing to reviewers flagged as FG21/1 specialists.
`requiresSeniorSignOff`	boolean	No	Explicitly require a LEAD_REVIEWER or FIRM_ADMIN to complete the job. Automatically forced to `true` when `vulnerabilityFlags` is non-empty — callers cannot opt out of senior sign-off on flagged cases.
`clientSegments`	object	No	Anonymised client segments used for bias / fairness monitoring (e.g. ageBand, riskProfile, productType). Values are plain strings and are aggregated across jobs on the `/v1/firm/me/bias` report — pick categorical labels rather than identifiers.

Responses

201Review job created401Unauthorized403Plan insufficient for principal services409IMPACT_ASSESSMENT_REQUIRED — the firm has the impact-assessment gate on (the default) and no approved assessment matches the modelProvider/modelVersion declared on this job. File one and have a senior sign off before retrying.422Document download failed

Field	Type	Req	Description
`id`	string	No
`firmId`	string	No
`documentType`	string	No
`clientReference`	string	No
`documentReference`	string	No
`status`	string	No	`QUEUEDASSIGNEDIN_REVIEWCOMPLETED`
`priority`	string	No	`STANDARDURGENT`
`outcome`	string \| null	No	`APPROVEDREJECTEDAPPROVED_WITH_MODIFICATIONS`
`assignedTo`	string \| null	No
`createdAt`	string (date-time)	No
`updatedAt`	string (date-time)	No
`modelProvider`	string \| null	No	AI model provider that produced the underlying advice.
`modelVersion`	string \| null	No	Specific model version that produced the underlying advice.
`modelConfiguration`	object	No	Inference parameters used for this generation. Defaults to an empty object when the request omits the field — the column is non-null in the database.
`vulnerabilityFlags`	string[]	No	FCA FG21/1 vulnerability drivers recorded for this job. Flagged jobs are routed exclusively to specialist or lead reviewers and always require senior sign-off.
`requiresSeniorSignOff`	boolean	No	Whether this job must be completed by a LEAD_REVIEWER or FIRM_ADMIN. Automatically true for any job with `vulnerabilityFlags` populated.
`clientSegments`	object	No	Anonymised categorical segments used to power the `/v1/firm/me/bias` fairness monitor. Defaults to an empty object when the request omits the field.
`ledgerRecordId`	string \| null	No	Ledger record id for the outcome event (DOCUMENT_APPROVED / MODIFIED / REJECTED) once the review completes. Use as the key to fetch the certificate PDF via `GET /v1/ledger/records/{id}/certificate`.
`certificateId`	string \| null	No	Certificate id, populated once cert-gen finishes after the review completes. Use for verify deep-links.

Example request

cURL

curl -X POST "https://api.bedrockcompliance.co.uk/v1/principal/jobs" \
  -H "X-Bedrock-Key: bk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "documentUrl": "https://example.com",
  "documentType": "<documentType>",
  "clientReference": "<clientReference>",
  "documentReference": "<documentReference>",
  "factFindSummary": {},
  "priority": "<priority>",
  "modelProvider": "openai",
  "modelVersion": "gpt-4o-2024-08-06",
  "modelConfiguration": {
    "temperature": 0.2,
    "topP": 0.95,
    "maxTokens": 2048
  },
  "vulnerabilityFlags": [
    "health",
    "life_event"
  ],
  "requiresSeniorSignOff": true,
  "clientSegments": {
    "ageBand": "65+",
    "riskProfile": "Cautious",
    "productType": "SIPP"
  }
}'

GET/v1/principal/jobs

List review jobs with pagination

Parameters

Parameter	In	Type	Req	Description
`page`	query	integer	No
`pageSize`	query	integer	No
`status`	query	string	No	Filter by job status

Responses

200Paginated list of review jobs401Unauthorized

Field	Type	Req
`data`	Job[]	No
`total`	integer	No
`page`	integer	No
`pageSize`	integer	No

Example request

cURL

curl -X GET "https://api.bedrockcompliance.co.uk/v1/principal/jobs" \
  -H "X-Bedrock-Key: bk_live_your_api_key"

GET/v1/principal/jobs/{id}

Get review job details with anonymised review actions

Parameters

Parameter	In	Type	Req	Description
`id`	path	string	Yes	Job ID

Responses

200Review job details401Unauthorized404Review job not found

Field	Type	Req	Description
`id`	string	No
`firmId`	string	No
`documentType`	string	No
`clientReference`	string	No
`documentReference`	string	No
`status`	string	No	`QUEUEDASSIGNEDIN_REVIEWCOMPLETED`
`priority`	string	No	`STANDARDURGENT`
`outcome`	string \| null	No	`APPROVEDREJECTEDAPPROVED_WITH_MODIFICATIONS`
`assignedTo`	string \| null	No
`createdAt`	string (date-time)	No
`updatedAt`	string (date-time)	No
`modelProvider`	string \| null	No	AI model provider that produced the underlying advice.
`modelVersion`	string \| null	No	Specific model version that produced the underlying advice.
`modelConfiguration`	object	No	Inference parameters used for this generation. Defaults to an empty object when the request omits the field — the column is non-null in the database.
`vulnerabilityFlags`	string[]	No	FCA FG21/1 vulnerability drivers recorded for this job. Flagged jobs are routed exclusively to specialist or lead reviewers and always require senior sign-off.
`requiresSeniorSignOff`	boolean	No	Whether this job must be completed by a LEAD_REVIEWER or FIRM_ADMIN. Automatically true for any job with `vulnerabilityFlags` populated.
`clientSegments`	object	No	Anonymised categorical segments used to power the `/v1/firm/me/bias` fairness monitor. Defaults to an empty object when the request omits the field.
`ledgerRecordId`	string \| null	No	Ledger record id for the outcome event (DOCUMENT_APPROVED / MODIFIED / REJECTED) once the review completes. Use as the key to fetch the certificate PDF via `GET /v1/ledger/records/{id}/certificate`.
`certificateId`	string \| null	No	Certificate id, populated once cert-gen finishes after the review completes. Use for verify deep-links.

Example request

cURL

curl -X GET "https://api.bedrockcompliance.co.uk/v1/principal/jobs/<id>" \
  -H "X-Bedrock-Key: bk_live_your_api_key"