Vendor analysis annotations
During the manual review (in_manual_analysis or in_compliance_analysis), the QI Tech analyst may open an annotation: a request for a clarification or a document. The analysis is not approved while there is an open annotation. At this stage, responding to an annotation is the only way to attach a document.
Annotation status
| Status | Description |
|---|---|
opened | Opened by QI Tech, waiting for a response. |
closed | Responded to by the manager, or closed automatically when the analysis ended. |
To find out whether there is an open annotation, list the analysis annotations with status=opened. The annotation_status=opened filter of the vendor listing only looks at the most recent annotation of the last analysis: an older annotation that is still open does not show up in it.
List annotations
| Profile | Host | Required permission |
|---|---|---|
| Manager | manager-api | Read |
| Consultant | consultant-api | Active integration |
Base URL for each host: Environments (Hosts).
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
status | string | No | opened or closed. Accepts several comma-separated values. |
limit | integer | No | Items per page, from 0 to 1000. Default: 10. |
page | integer | No | Page, starting at 0. Default: 0. |
Returns the analysis annotations, from the most recent to the oldest.
Response
{
"data": [
{
"annotation_key": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
"annotation_message": "Enviar comprovante de endereço atualizado.",
"annotation_response": null,
"annotation_datetime": "2026-11-03 10:00:00.527114",
"analysis_key": "8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13",
"status": "opened",
"attached_document_key": null,
"response_datetime": null
}
],
"limit": 10,
"page": 0,
"is_last_page": true
}
Attributes of each annotation
| Field | Type | Description |
|---|---|---|
annotation_key | string | Annotation key (UUID). |
annotation_message | string | Analyst's request, up to 200 characters. |
annotation_response | string | Manager's response, or null. |
annotation_datetime | string | When the annotation was opened. |
analysis_key | string | Analysis the annotation belongs to. |
status | string | opened or closed. |
attached_document_key | string | Document attached in the response, or null. |
response_datetime | string | When the response was sent, or null. |
Retrieve an annotation by key
Permission: Manager (manager-api): Read. Consultant (consultant-api): Active integration. Returns an annotation, with the structure of each annotation.
Respond to an annotation
Responds to the annotation and closes it. Only accepted with the analysis in in_manual_analysis or in_compliance_analysis; in any other status, including with the analysis concluded, it returns 405 (VRG000011).
The response can carry a document in one of these ways (never both):
- a new document, in Base64. It follows the type and format rules of Documents and replaces the previous one of the same type;
- the key of a document that is already in the analysis.
| Profile | Host | Required permission |
|---|---|---|
| Manager | manager-api | Write |
| Consultant | consultant-api | Active integration |
Base URL for each host: Environments (Hosts).
{
"annotation_response": "Segue o comprovante de endereço atualizado.",
"name": "comprovante_endereco.pdf",
"document_type": "proof_of_residence",
"document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwKL0xlbmd0aCAzIDAgUgo..."
}
{
"annotation_response": "O documento pedido já está na análise.",
"attached_document_key": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a"
}
Body attributes
| Field | Type | Required | Description |
|---|---|---|---|
annotation_response | string | Yes | Response, up to 1000 characters. |
document_b64 | string | No | New document in Base64. Requires name and document_type. |
name | string | Conditional | File name, from 1 to 255 characters. Required with document_b64. |
document_type | string | Conditional | Document type, one of the accepted types. Required with document_b64. |
related_party_key | string | No | Attaches the new document to this related party instead of the vendor. Only with document_b64. |
attached_document_key | string | No | Key of a document already uploaded in this analysis (of the vendor or of a party). Cannot be combined with document_b64. |
Response
{
"annotation_key": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
"annotation_message": "Enviar comprovante de endereço atualizado.",
"annotation_response": "Segue o comprovante de endereço atualizado.",
"annotation_datetime": "2026-11-03 10:00:00.527114",
"analysis_key": "8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13",
"status": "closed",
"attached_document_key": "f3a4b5c6-d7e8-4f9a-0b1c-2d3e4f5a6b7c",
"response_datetime": "2026-11-03 11:20:07.381946+00:00"
}
Errors
Annotation already responded to
You have already responded to this annotation.
{
"title": "Annotation Already Responded",
"description": "Annotation with key 9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d is already responded.",
"translation": "Anotacao com chave 9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d esta respondida.",
"code": "VRG000013"
}
Analysis outside manual review
The analysis is neither in in_manual_analysis nor in in_compliance_analysis: for example, it has already been concluded or was withdrawn from the queue. An annotation closed automatically at the end of the analysis no longer accepts a response either.
{
"title": "Operation Status does not allow annotations",
"description": "Operation with key 8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13 is on status approved, annotations can only be created or responded on in_manual_analysis or in_compliance_analysis.",
"translation": "Operacao com chave 8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13 esta no status approved, apontamentos so podem ser criados ou respondidos nos status in_manual_analysis ou in_compliance_analysis.",
"code": "VRG000011"
}
code | When it happens |
|---|---|
VRG000007 | The analysis_key does not exist. If the analysis belongs to a vendor you cannot see, the code is VRG000014. |
VRG000012 | The annotation_key does not exist or does not belong to this analysis. |
VRG000071 | attached_document_key is not a document of this analysis. |
VRG000053 | related_party_key is not linked to this analysis or is inactive. |
The type, size and format errors of the new document are the same as in Documents (VRG000081, VRG000082, VRG000080, VRG000067, VRG000097). Combining document_b64 with attached_document_key, or sending name, document_type or related_party_key without document_b64, returns QIT000001.
Authentication, permission and host errors: see API Errors.