Enviar KYC da subconta (multipart)
POST
/api/subaccounts/{{subaccount_id}}/kyc
Autenticação
subaccounts:write e a conta precisa da flag white-label habilitada. Sem a flag, a rota responde 404 (invisível). Sem o header → 401. Escopo insuficiente → 403 insufficient_scope.Não defina o header Content-Typemanualmente. Esta rota émultipart/form-datae o cliente HTTP gera oboundaryautomaticamente. Defini-lo à mão quebra o parsing.
Enviar KYC da subconta
subaccounts:writeContent-Type:
multipart/form-datastatus da submissão. Ao enviar com sucesso, a subconta passa para kycStatus = IN_REVIEW e a submissão é criada com status = RECEIVED. A análise é feita por um operador Dotfy.Campos do formulário (multipart)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
payload | text (JSON em string) | sim | Dados cadastrais da subconta. Deve ser JSON válido. |
docFront | file | sim | Frente do documento de identidade. |
docBack | file | não | Verso do documento (quando aplicável). |
selfie | file | sim | Selfie do titular com o documento. |
extraDocs | file (repetível) | não | Até 5 documentos complementares. |
image/jpeg, image/png, image/webp, application/pdf; extensão jpg/jpeg/png/webp/pdf; tamanho máximo 10MB por arquivo.Resposta
201 Created com { submission: { id, status, createdAt } }. status inicial é RECEIVED. Consulte o andamento em GET /api/subaccounts/{id}/kyc.Códigos de erro
| HTTP | code | Quando |
|---|---|---|
400 | — | payload ausente, payload não é JSON válido, docFront/selfie ausentes, ou arquivo com MIME/extensão/tamanho inválido. |
401 | — | Sem header Authorization ou chave inválida/revogada. |
403 | insufficient_scope | Chave sem o escopo subaccounts:write. |
404 | — | Flag white-label desabilitada, subconta inexistente ou não pertence ao master (invisibilidade anti-IDOR). |
409 | KYC_PENDING | Já existe uma submissão em análise (RECEIVED/IN_REVIEW) para esta subconta. |
422 | KYC_ALREADY_APPROVED | O KYC desta subconta já está aprovado — nada a reenviar. |
Exemplo cURL
429 ao exceder).Requisição
Parâmetros Header
Parâmetros Bodymultipart/form-data
Respostas
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --globoff '/api/subaccounts/{{subaccount_id}}/kyc' \
--header 'Authorization: Bearer <token>' \
--form 'payload="{
\"fullName\": \"Empresa Exemplo LTDA\",
\"taxId\": \"12345678000199\",
\"birthDate\": \"1990-05-12\",
\"address\": {
\"street\": \"Av. Paulista, 1000\",
\"city\": \"São Paulo\",
\"state\": \"SP\",
\"zipCode\": \"01310100\"
}
}"' \
--form 'docFront=@""' \
--form 'docBack=@""' \
--form 'selfie=@""' \
--form 'extraDocs=@""'Response Response Example
201 - Sucesso (201) — submissão recebida
{
"submission": {
"id": "clkycsub0001",
"status": "RECEIVED",
"createdAt": "2026-06-13T14:20:00.000Z"
}
}Modificado em 2026-07-02 06:57:27