API Reference

Review API

Review job submission and tracking

Endpoints in this group

POST/v1/principal/uploadsGet a presigned URL to upload an advice document
POST/v1/principal/jobsSubmit an uploaded 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/uploads

Get a presigned URL to upload an advice document

Step 1 of the two-step submission flow. Returns a short-lived presigned S3 URL the client can `PUT` the raw document bytes to, plus the `documentKey` to pass back to `POST /v1/principal/jobs`. The presigned URL is single-use and scoped to the firm — Bedrock never proxies the document bytes itself.

Request body

Field	Type	Req	Description
`filename`	string	Yes	Original filename, used as the object key suffix. The full key is namespaced under the firm so collisions across firms are impossible.
`contentType`	string	No	MIME type used to sign the upload URL. Must match the `Content-Type` header on the subsequent `PUT`. Defaults to `application/pdf`.

Responses

200Presigned upload URL and document key401Unauthorized

Field	Type	Req	Description
`uploadUrl`	string (uri)	Yes	Presigned S3 URL — `PUT` the document bytes here within the URL’s expiry window.
`documentKey`	string	Yes	Opaque object key. Pass this back to `POST /v1/principal/jobs` as the `documentKey` field after the upload completes.

Example request

curl

curl -X POST "https://api.bedrockcompliance.co.uk/v1/principal/uploads" \
  -H "X-Bedrock-Key: bk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "filename": "suitability-12345.pdf",
  "contentType": "application/pdf"
}'

POST/v1/principal/jobs

Submit an uploaded document for review

Step 2 of the two-step submission flow. The `documentKey` must be the value returned from a prior `POST /v1/principal/uploads` call — Bedrock reads the document bytes from the uploads bucket, hashes them, copies them into the immutable ledger bucket, and writes a `DOCUMENT_SUBMITTED` ledger event. There is no Bedrock-initiated download.

Request body

Field	Type	Req	Description
`documentKey`	string	Yes	Opaque object key returned from `POST /v1/principal/uploads`. The document must already have been uploaded to the presigned URL when this call is made.
`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`
`aiContext`	AiContext	No
`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/bias` report — pick categorical labels rather than identifiers.

Responses

201Review job created401Unauthorized403Plan insufficient for principal services404DOCUMENT_NOT_FOUND — the `documentKey` does not resolve to an uploaded object in the firm's uploads bucket. Make sure the `PUT` to the presigned upload URL completed successfully before submitting the job.409IMPACT_ASSESSMENT_REQUIRED — the firm has the impact-assessment gate on (the default) and no approved assessment matches the aiContext.model.provider/version 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
`documentReference`	string	No	Firm-assigned stable identifier for the document.
`documentType`	string	No	One of the `DocumentType` enum values.
`documentUrl`	string	No	Internal `s3://` URI of the canonical copy in the immutable ledger bucket. Not the upload URL — once the job is created the original `documentKey` is no longer relevant.
`documentHash`	string	No	sha256 of the document bytes as uploaded. The same hash is anchored on the `DOCUMENT_SUBMITTED` ledger record.
`clientReference`	string	No	Firm-assigned stable client identifier (not a name).
`factFindSummary`	object	No	Structured summary of the client fact find as supplied at submission.
`status`	string	No	`QUEUEDASSIGNEDIN_REVIEWESCALATEDAPPROVEDMODIFIEDREJECTEDCANCELLED`
`priority`	string	No	`STANDARDURGENT`
`outcome`	string \| null	No	`APPROVEDAPPROVED_WITH_MODIFICATIONSREJECTED`
`outcomeReason`	string \| null	No	Reviewer-supplied reason recorded with the decision (most relevant on rejections).
`modifications`	string \| null	No	Verbatim modifications recorded when the outcome is `APPROVED_WITH_MODIFICATIONS`.
`assignedReviewerId`	string \| null	No	FK → User. Set when the job moves to `ASSIGNED`.
`assignedAt`	string (date-time) \| null	No
`completedAt`	string (date-time) \| null	No
`submittedAt`	string (date-time)	No
`slaDeadline`	string (date-time)	No	ISO 8601 deadline (`submittedAt + 48h`). Crossing this without a decision triggers an `SLA_BREACHED` ledger event.
`aiContext`	any \| null	No	AI lineage for the advice. Contains model identity, inputs, outputs, decision factors, confidence, and guardrails. Null when the submitting firm did not provide AI context.
`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/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 '{
  "documentKey": "<documentKey>",
  "documentType": "<documentType>",
  "clientReference": "<clientReference>",
  "documentReference": "<documentReference>",
  "factFindSummary": {},
  "priority": "<priority>",
  "aiContext": {},
  "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	Description
`data`	Job[]	Yes
`pagination`	Pagination	Yes

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
`documentReference`	string	No	Firm-assigned stable identifier for the document.
`documentType`	string	No	One of the `DocumentType` enum values.
`documentUrl`	string	No	Internal `s3://` URI of the canonical copy in the immutable ledger bucket. Not the upload URL — once the job is created the original `documentKey` is no longer relevant.
`documentHash`	string	No	sha256 of the document bytes as uploaded. The same hash is anchored on the `DOCUMENT_SUBMITTED` ledger record.
`clientReference`	string	No	Firm-assigned stable client identifier (not a name).
`factFindSummary`	object	No	Structured summary of the client fact find as supplied at submission.
`status`	string	No	`QUEUEDASSIGNEDIN_REVIEWESCALATEDAPPROVEDMODIFIEDREJECTEDCANCELLED`
`priority`	string	No	`STANDARDURGENT`
`outcome`	string \| null	No	`APPROVEDAPPROVED_WITH_MODIFICATIONSREJECTED`
`outcomeReason`	string \| null	No	Reviewer-supplied reason recorded with the decision (most relevant on rejections).
`modifications`	string \| null	No	Verbatim modifications recorded when the outcome is `APPROVED_WITH_MODIFICATIONS`.
`assignedReviewerId`	string \| null	No	FK → User. Set when the job moves to `ASSIGNED`.
`assignedAt`	string (date-time) \| null	No
`completedAt`	string (date-time) \| null	No
`submittedAt`	string (date-time)	No
`slaDeadline`	string (date-time)	No	ISO 8601 deadline (`submittedAt + 48h`). Crossing this without a decision triggers an `SLA_BREACHED` ledger event.
`aiContext`	any \| null	No	AI lineage for the advice. Contains model identity, inputs, outputs, decision factors, confidence, and guardrails. Null when the submitting firm did not provide AI context.
`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/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"