Skip to main content

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.

Paginated Annotations Query​

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

Request​

ENDPOINT
/assignor_registry/public/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotations
METHOD
GET

Query params​

FieldTypeDescriptionCharacters
limitintegerObject limit per page (default 10, maximum 50).-
pageintegerDesired 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
}

Treatable Errors​

CodeHTTPCauseHow to resolve
ASR000026404Agent not found for the AGENT-KEY provided.Check whether the authenticated agent's key is correct.

Annotation Query by Key​

Request​

ENDPOINT
/assignor_registry/public/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.

Treatable Errors​

CodeHTTPCauseHow to resolve
ASR000026404Agent not found for the AGENT-KEY provided.Check whether the authenticated agent's key is correct.
ASR000004404Assignor not found for the assignor_registry_key provided.Check whether the assignor_registry_key is correct and belongs to the authenticated agent.
ASR000033404Analysis not found for the analysis_key provided.Check whether the analysis_key is correct.
ASR000043404Annotation not found for the annotation_key provided.Check whether the annotation_key belongs to the analysis indicated.

Answering an Annotation​

Submits the agent's answer to an annotation. Optionally, you may attach a PDF document that supports or complements the answer.

Request​

ENDPOINT
/assignor_registry/public/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY
METHOD
PUT
Request Body
{
    "response": "Case records attached.",
    "document_b64": "aGVsbG8gd29ybGQgaWYgeW91IGRlY29kZWQgbWUsIGJlIGNhcmVmdWwuIEl0IG11c3QgYmUgYSBQREYgRmlsZSBvdGhlcndpc2UgSSB3aWxsIHJhaXNlIGFuIEVycm9yLg=="
}

Answer Object​

FieldTypeDescriptionCharacters
response *stringAnswer text for the annotation.1 - 3000
document_b64stringBinary of the PDF file, Base64-encoded.-

*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"
}

Treatable Errors​

CodeHTTPCauseHow to resolve
ASR000026404Agent not found for the AGENT-KEY provided.Check whether the authenticated agent's key is correct.
ASR000004404Assignor not found for the assignor_registry_key provided.Check whether the assignor_registry_key is correct and belongs to the authenticated agent.
ASR000033404Analysis not found for the analysis_key provided.Check whether the analysis_key is correct.
ASR000043404Annotation not found for the annotation_key provided.Check whether the annotation_key belongs to the analysis indicated.
ASR000045400The annotation is no longer in the open status and no longer accepts answers.Only annotations with the open status can be answered.
ASR000044400The annotation has already been answered.Each annotation accepts only one answer.
ASR000005400Invalid file format.Send document_b64 as a valid base64 string.
ASR000060400The file submitted is not a valid PDF.The decoded content of document_b64 must be a PDF.
ASR000059400File size exceeds the limit.Reduce the PDF size before submitting (the limit is stated in the error message).

Annotation Document Query​

Retrieves a temporary URL to download the document attached to an annotation.

Request​

ENDPOINT
/assignor_registry/public/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY/document/DOCUMENT_KEY
METHOD
GET

Response​

STATUS
200
Response Body
{
    "document_url": "https://assignor-bucket.s3.amazonaws.com/8e515a17-8b4d-49a3-aed6-47c9574e426a?..."
}
info

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

Treatable Errors​

CodeHTTPCauseHow to resolve
ASR000026404Agent not found for the AGENT-KEY provided.Check whether the authenticated agent's key is correct.
ASR000004404Assignor not found for the assignor_registry_key provided.Check whether the assignor_registry_key is correct and belongs to the authenticated agent.
ASR000033404Analysis not found for the analysis_key provided.Check whether the analysis_key is correct.
ASR000043404Annotation not found for the annotation_key provided.Check whether the annotation_key belongs to the analysis indicated.
ASR000006404Document not found for the document_key provided.Check whether the document_key corresponds to the document attached to the annotation.

Annotation Object​

FieldTypeDescription
annotation_keystringUnique identifier of the annotation.
analysis_keystringKey of the analysis the annotation belongs to.
assignor_registry_keystringAssignor's key.
statusstringCurrent status of the annotation. See Annotation Status.
origin_typestringOrigin of the annotation. See Annotation Origin Type.
annotation_datetimestringDate and time the annotation was created (ISO 8601).
messagestringAnnotation message recorded by the QI DTVM team.
responsestringAnswer submitted by the agent (present after the answer).
response_datetimestringDate and time of the answer (present after the answer).
attached_document_keystringKey of the document attached to the answer (when there is one).

Annotation Status​

EnumeratorDescription
createdAnnotation created, not yet made available.
openOpen and awaiting the agent's answer.
closedAnswered and closed.

Annotation Origin Type​

EnumeratorDescription
complianceAnnotation originated by the Compliance team (manual analysis).
risk_analysisAnnotation originated by the Risk team.
internalAnnotation originated in the internal validation.