Vendor retrieval
Lists the vendors visible to you and retrieves a vendor by key with all its data: approved data, related parties, bank accounts, signer groups and the last analysis.
List vendors
Available on
| Profile | Host | Required permission |
|---|---|---|
| Manager | manager-api | Read |
| Consultant | consultant-api | Active integration |
Base URL for each host: Environments (Hosts).
ENDPOINT
/vendor_registry/vendorsMETHOD
GETQuery parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
status | string | No | Vendor status: pending_analysis, active, inactive, expired. Accepts several comma-separated values. |
name | string | No | Beginning of the vendor name, case-insensitive. |
document_number | string | No | Exact CPF or CNPJ, with or without punctuation. |
analysis_status | string | No | Status of the vendor's last analysis. Accepts several comma-separated values. See analysis status. |
annotation_status | string | No | Status of the most recent annotation of the last analysis: opened or closed. Vendors without annotations are left out of the result when this filter is used. |
agent_document_number | string | No | Exact CPF or CNPJ of the agent that owns the vendor, with or without punctuation. |
agent_name | string | No | Beginning of the name of the agent that owns the vendor, case-insensitive. |
limit | integer | No | Items per page, from 0 to 1000. Default: 10. |
page | integer | No | Page, starting at 0. Default: 0. |
Returns the vendors from newest to oldest. Included:
- the vendors you created;
- the ones you see through a consultant's contract;
- the vendor that represents your own manager, created and approved automatically when it was registered in the service.
An unknown value in status or analysis_status does not raise an error: the search just finds nothing.
Example call
GET /vendor_registry/vendors?status=active,expired&limit=50
Response
STATUS
200Response body
{
"data": [
{
"vendor_key": "5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57",
"name": "AUDITORES EXEMPLO S.A.",
"document_number": "44.555.666/0001-81",
"email": "contato@auditoresexemplo.com.br",
"address": {
"postal_code": "01310-100",
"street": "Avenida Paulista",
"number": "1000",
"complement": "10º andar",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"uf": "SP",
"country": "BRA"
},
"person_type": "legal_person",
"status": "active",
"block_reason": null,
"expiration_date": "2028-11-09",
"agents": [
{
"agent_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
"agent_type": "manager",
"name": "EXEMPLO GESTORA LTDA",
"document_number": "22.333.444/0001-81",
"permission_type": "owner"
}
],
"related_parties": [
{
"related_party_key": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"name": "João da Silva",
"document_number": "123.456.789-09",
"email": "joao.silva@auditoresexemplo.com.br",
"related_party_type": "administrator",
"is_representative": true,
"ownership_percentage": 50.0,
"nationality": "BRA",
"passport_number": null,
"status": "active"
}
],
"bank_accounts": [
{
"bank_account_key": "0f9e8d7c-6b5a-4f3e-2d1c-0b9a8f7e6d5c",
"transfer_type": "pix",
"main_account": true,
"status": "active",
"pix_key": "44555666000181"
}
],
"signer_groups": [
{
"signer_group_key": "7e6d5c4b-3a2f-4e1d-9c8b-7a6f5e4d3c2b",
"minimum_required_signers": 1,
"is_default": true,
"signers": [
{
"name": "João da Silva",
"document_number": "123.456.789-09",
"email": "joao.silva@auditoresexemplo.com.br",
"is_required_signer": true
}
],
"status": "valid",
"analysis_key": "8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13"
}
],
"last_analysis": {
"analysis_key": "8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13",
"analysis_number": 1,
"status": "approved",
"analysis_related_parties": [
{
"analysis_related_party_key": "c0ffee00-1111-4222-8333-444455556666",
"related_party_key": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"name": "João da Silva",
"document_number": "123.456.789-09"
}
],
"documents": [
{
"document_name": "contrato_social.pdf",
"document_key": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
"document_type": "social_contract",
"file_type": "pdf",
"analysis_key": "8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13",
"status": "valid",
"reference_date": "2025-03-14",
"data": null
}
],
"annotations": [],
"last_updated": "2026-11-09 14:03:21.123456",
"reproval_reason": null,
"reproval_details": null,
"signer_groups": []
}
}
],
"limit": 10,
"page": 0,
"is_last_page": true
}
Vendor attributes
| Field | Type | Description |
|---|---|---|
vendor_key | string | Vendor key (UUID). |
name | string | Approved name; before the first approval, the one given on creation. |
document_number | string | CPF or CNPJ with punctuation. |
email | string | Approved email (before the first approval, the one given on creation), or null. |
address | object | Approved address, or null before the first approval. Same structure as in the registration data. |
person_type | string | natural_person or legal_person. |
status | string | pending_analysis, active, inactive or expired. See vendor status. |
block_reason | string | compliance_reproval when the vendor was definitively rejected; otherwise null. |
expiration_date | string | End of the registration validity, YYYY-MM-DD (two years after approval), or null if never approved and for the vendor that represents the agent itself. |
agents | array | Agents (managers and consultants) with access to the vendor: agent_key, agent_type, name, document_number and permission_type (owner or viewer). |
related_parties | array | Related parties in any status. See Related parties. |
bank_accounts | array | Bank accounts in any status. See Bank account. |
signer_groups | array | Signer groups in any status. See Signer group. |
last_analysis | object | Last analysis: analysis_key, analysis_number, status, analysis_related_parties (linked parties, with analysis_related_party_key, related_party_key, name, document_number), documents (without URL), annotations, last_updated, reproval_reason, reproval_details, signer_groups. null if there is no analysis. |
Retrieve a vendor by key
Available on
| Profile | Host | Required permission |
|---|---|---|
| Manager | manager-api | Read |
| Consultant | consultant-api | Active integration |
Base URL for each host: Environments (Hosts).
ENDPOINT
/vendor_registry/vendor/{vendor_key}METHOD
GETPath parameters
| Parameter | Type | Description |
|---|---|---|
vendor_key | string | Vendor key (UUID). |
Response
STATUS
200A vendor, with the same structure as each item of data in the listing.
Errors
STATUS
404Vendor not found
The vendor_key does not exist or the vendor is not visible to you.
{
"title": "Vendor not found",
"description": "Vendor with the key 5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57 was not found.",
"translation": "O fornecedor com a chave 5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57 nao foi encontrada.",
"code": "VRG000014"
}
Manager not registered in the service
In the listing: your manager is not registered in the vendor service yet. Contact integracao.dtvm@qitech.com.br.
{
"title": "Agent not found",
"description": "Agent with the key a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c was not found.",
"translation": "O agente com a chave a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c nao foi encontrado.",
"code": "VRG000043"
}
STATUS
400code | When it happens |
|---|---|
QIT000010 | limit or page is out of range or not numeric. |
Authentication, permission and host errors: see API Errors.