Compliance annotations

During the Assignor's registration analysis, the Compliance, Risk or internal validation teams may record annotations. An annotation is a request or question addressed to the agent responsible for the registration, which must be answered for the analysis to proceed.

Whenever an annotation is created, it starts in the open status and, if configured, an Annotation Webhook is fired notifying the opening. An e-mail is also sent to the recipients configured for the agent. After the agent answers the annotation, it moves to the closed status and a new webhook is fired.

info

Annotations only exist while the analysis is in one of the in_manual_analysis, pending_internal_validation or in_risk_analysis statuses. Each annotation accepts only one answer.

Who does what:

Action	Manager	Consultant	Assignor
List the analysis annotations	Yes	Yes	No (use the webhook and the query by key)
Query annotation and document	Yes	Yes	Yes
Answer	`PUT .../annotation/{annotation_key}`	`PUT .../annotation/{annotation_key}`	`PUT .../annotation/{annotation_key}/response`

Paginated Annotations Query

Retrieves the list of annotations for an analysis, allowing the agent to identify what needs to be answered.

Available on

Profile	Host	Required permission
Manager	`manager-api`	Read
Consultant	`consultant-api`	View Assignors

Base URL for each host: Environments (Hosts).

The assignor does not have this listing: it receives the annotation webhook, which carries the annotation_key, and queries the annotation by key.

Request

ENDPOINT

/assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotations

METHOD

GET

Query params

Field	Type	Description	Characters
`limit`	integer	Object limit per page (default 10, maximum 50).	-
`page`	integer	Desired page (starts at 0).	-

Response

STATUS

200

Response Body
{
    "data": [
        {
            "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f",
            "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
            "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
            "status": "open",
            "origin_type": "compliance",
            "annotation_datetime": "2025-01-22T20:30:23Z",
            "message": "Attach details of case XXXXXXXXXXX."
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}

Errors

Status	Code	When it happens
404	`ASR000026`	The authenticated agent is not enabled in the assignor registry.
400	—	`limit` above `50` or negative `page`.

Authentication, permission and host errors: see API Errors.

Annotation Query by Key

Available on

Profile	Host	Required permission
Manager	`manager-api`	Read
Consultant	`consultant-api`	View Assignors
Assignor	`assignor-api`	Read

Base URL for each host: Environments (Hosts).

Request

ENDPOINT

/assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY

METHOD

GET

Response

STATUS

200

Response Body
{
    "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f",
    "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
    "status": "closed",
    "origin_type": "compliance",
    "annotation_datetime": "2025-01-22T20:30:23Z",
    "message": "Attach details of case XXXXXXXXXXX.",
    "response": "Case records attached.",
    "response_datetime": "2025-01-23T14:05:11Z",
    "attached_document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a"
}

info

The response, response_datetime and attached_document_key fields are only returned when the annotation has already been answered and/or has a document attached.

Errors

Status	Code	When it happens
404	`ASR000004`	`assignor_registry_key` not found, or the agent has no access to this assignor.
404	`ASR000033`	`analysis_key` not found.
404	`ASR000043`	`annotation_key` does not belong to the analysis indicated.

Authentication, permission and host errors: see API Errors.

Answering an Annotation

Submits the answer to an open annotation. Optionally, you may attach a PDF document (up to 20 MB) that supports or complements the answer. Once answered, the annotation moves to closed and the annotation webhook is fired.

The manager and the consultant answer through the PUT on the annotation itself; the assignor answers through the PUT on /response. The body and the response are the same.

Available on

Profile	Host	Required permission
Manager	`manager-api`	Write
Consultant	`consultant-api`	Register Assignor

Base URL for each host: Environments (Hosts).

Request (manager and consultant)

ENDPOINT

/assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY

METHOD

PUT

Available on

Profile	Host	Required permission
Assignor	`assignor-api`	Write

Base URL for each host: Environments (Hosts).

Request (assignor)

ENDPOINT

/assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY/response

METHOD

PUT

Request Body

Request Body
{
    "response": "Case records attached.",
    "document_b64": "JVBERi0xLjQK..."
}

Answer Object

Field	Type	Description	Characters
`response` *	string	Answer text for the annotation.	1 - 3000
`document_b64`	string	PDF file, Base64-encoded. Up to 20 MB.	-

*Required fields.

Response

STATUS

202

Response Body
{
    "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f",
    "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
    "status": "closed",
    "origin_type": "compliance",
    "annotation_datetime": "2025-01-22T20:30:23Z",
    "message": "Attach details of case XXXXXXXXXXX.",
    "response": "Case records attached.",
    "response_datetime": "2025-01-23T14:05:11Z",
    "attached_document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a"
}

Errors

Status	Code	When it happens
404	`ASR000004`	`assignor_registry_key` not found, or the agent has no access to this assignor.
404	`ASR000033`	`analysis_key` not found.
404	`ASR000043`	`annotation_key` does not belong to the analysis indicated.
400	`ASR000045`	The annotation is not `open`.
400	`ASR000044`	The annotation has already been answered. Each annotation accepts a single answer.
400	`ASR000005`	`document_b64` is not valid Base64.
400	`ASR000060`	The content of `document_b64` is not a PDF.
400	`ASR000059`	The PDF exceeds 20 MB.

Authentication, permission and host errors: see API Errors.

Annotation Document Query

Retrieves a temporary URL to download the document attached to an annotation. The DOCUMENT_KEY is the annotation's attached_document_key.

Available on

Profile	Host	Required permission
Manager	`manager-api`	Read
Consultant	`consultant-api`	View Assignors
Assignor	`assignor-api`	Read

Base URL for each host: Environments (Hosts).

Request

ENDPOINT

/assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY/document/DOCUMENT_KEY

METHOD

GET

Response

STATUS

200

Response Body
{
    "document_url": "https://URL_TEMPORARIA_DO_DOCUMENTO"
}

info

The document_url returned is a pre-signed URL valid for 24 hours.

Errors

Status	Code	When it happens
404	`ASR000004`	`assignor_registry_key` not found, or the agent has no access to this assignor.
404	`ASR000033`	`analysis_key` not found.
404	`ASR000043`	`annotation_key` does not belong to the analysis indicated.
404	`ASR000006`	`DOCUMENT_KEY` is not the document attached to the annotation.

Authentication, permission and host errors: see API Errors.

Annotation Object

Field	Type	Description
`annotation_key`	string	Unique identifier of the annotation.
`analysis_key`	string	Key of the analysis the annotation belongs to.
`assignor_registry_key`	string	Assignor's key.
`status`	string	Current status of the annotation. See Annotation Status.
`origin_type`	string	Origin of the annotation. See Annotation Origin Type.
`annotation_datetime`	string	Date and time the annotation was created (ISO 8601).
`message`	string	Annotation message recorded by the QI DTVM team.
`response`	string	Answer submitted by the agent (present after the answer).
`response_datetime`	string	Date and time of the answer (present after the answer).
`attached_document_key`	string	Key of the document attached to the answer (when there is one).

Annotation Status

Enumerator	Description
open	Open and awaiting the agent's answer.
closed	Answered and closed. QI DTVM may reopen it (it goes back to `open`).

Annotation Origin Type

Enumerator	Description
compliance	Annotation originated by the Compliance team (manual analysis).
risk_analysis	Annotation originated by the Risk team.
internal	Annotation originated in the internal validation.

Paginated Annotations Query​

Request​

Query params​

Response​

Errors​

Annotation Query by Key​

Request​

Response​

Errors​

Answering an Annotation​

Request (manager and consultant)​

Request (assignor)​

Request Body​

Answer Object​

Response​

Errors​

Annotation Document Query​

Request​

Response​

Errors​

Annotation Object​

Annotation Status​

Annotation Origin Type​

Paginated Annotations Query

Request

Query params

Response

Errors

Annotation Query by Key

Request

Response

Errors

Answering an Annotation

Request (manager and consultant)

Request (assignor)

Request Body

Answer Object

Response

Errors

Annotation Document Query

Request

Response

Errors

Annotation Object

Annotation Status

Annotation Origin Type