Increase limits
Raise a COMPANY subaccount's operating limits by submitting Proof of Address (company and UBO) and Proof of Financial Capacity.
Overview
To raise a COMPANY subaccount's operating limits, first complete KYB, then submit three documents:
| Document | documentType | Proves | Submit with |
|---|---|---|---|
| Company address | PROOF-OF-ADDRESS-COMPANY | The registered business address | POST /api/kyb/proof-of-address · addressType: "COMPANY" |
| UBO address | PROOF-OF-ADDRESS | The Ultimate Beneficial Owner's residence | POST /api/kyb/proof-of-address · addressType: "UBO" |
| Financial capacity | PROOF-OF-FINANCIAL-CAPACITY | That the company's funds or income back the declared volume | POST /api/kyb/proof-of-financial-capacity |
Higher limits apply once all three attempts are APPROVED. The same financial capacity submission also unlocks USD operations.
Document requirements
Applies to all three documents:
- Single-sided PDF. Multi-page scans and images are rejected in review.
- Dated within the last 3 months. A document collected during your own onboarding may be accepted up to 12 months old.
- Up to ~10MB when you send the optional inline
documentcopy. - Third-party issued and legible, with the holder's name matching the KYB data.
Flow
- Confirm the
COMPANYsubaccount's KYB isAPPROVED. - Company address — register a
PROOF-OF-ADDRESS-COMPANYdocument,PUTthe PDF, poll untilready: true, then submit it withaddressType: "COMPANY". - UBO address — register a
PROOF-OF-ADDRESSdocument,PUTthe PDF, poll untilready: true, then submit it withaddressType: "UBO". - Financial capacity — register a
PROOF-OF-FINANCIAL-CAPACITYdocument,PUTthe PDF, poll untilready: true, then submit it toPOST /api/kyb/proof-of-financial-capacity. - Poll each of the three
attemptIds untilstatus: APPROVED.
Steps 2–4 can run in parallel.
Uploading a Proof of Address document
Use the document upload endpoints with the matching documentType.
1. Register the document — POST /api/kyc/document
curl --request POST \
--url https://api.hodle.com.br/api/kyc/document \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{ "subAccountId": "c852df87-...", "documentType": "PROOF-OF-ADDRESS-COMPANY" }'| Field | Type | Required | Description |
|---|---|---|---|
subAccountId | string | Yes | The COMPANY subaccount the document belongs to. |
documentType | string | Yes | PROOF-OF-ADDRESS-COMPANY (company address) or PROOF-OF-ADDRESS (UBO residence). |
{
"success": true,
"data": {
"documentId": "doc_poa_9a1...",
"uploadUrlFront": "https://uploads.hodle.com.br/..."
}
}2. Upload the PDF
curl --request PUT \
--url "$UPLOAD_URL_FRONT" \
--header "If-None-Match: *" \
--header "Content-Type: application/pdf" \
--data-binary "@company-address.pdf"3. Check readiness — GET /api/kyc/document/{documentId}
curl --url "https://api.hodle.com.br/api/kyc/document/doc_poa_9a1...?subAccountId=c852df87-..." \
--header "Authorization: Bearer $API_KEY"{ "success": true, "data": { "documentId": "doc_poa_9a1...", "ready": true } }Poll until ready: true, then submit the document below.
POST /api/kyb/proof-of-address
Submit one ready document. Call it once for the company address and once for the
UBO address — each call returns its own attemptId.
Request
curl --request POST \
--url https://api.hodle.com.br/api/kyb/proof-of-address \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{
"subAccountId": "c852df87-ac61-4259-8242-6451658dfedb",
"uploadedPoAId": "doc_poa_9a1...",
"addressType": "COMPANY"
}'const res = await fetch('https://api.hodle.com.br/api/kyb/proof-of-address', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.HODLE_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
subAccountId,
uploadedPoAId,
addressType: 'COMPANY',
}),
})
const data = await res.json()import os, requests
res = requests.post(
"https://api.hodle.com.br/api/kyb/proof-of-address",
headers={
"Authorization": f"Bearer {os.environ['HODLE_API_KEY']}",
"Content-Type": "application/json",
},
json={
"subAccountId": sub_account_id,
"uploadedPoAId": uploaded_poa_id,
"addressType": "COMPANY",
},
)
data = res.json()Parameters
| Field | Type | Required | Description |
|---|---|---|---|
subAccountId | string | Yes | The COMPANY subaccount's id. |
uploadedPoAId | string | Yes | documentId of the uploaded Proof of Address PDF, with ready: true. |
addressType | string | Yes | COMPANY for the company address, UBO for the beneficial owner's residence. |
desiredMonthlyLimit | integer | No | Positive monthly ceiling in BRL cents, used when custom limit requests are enabled for your account; otherwise ignored. Defaults to 50000000 (R$ 500,000). Documents submitted while a request is open join that request. |
document | string | No | Optional base64 PDF copy, up to ~10 MB of binary. The uploaded document ID identifies the document reviewed. |
documentMimeType | string | No | MIME type of document, e.g. application/pdf. |
Response
{
"success": true,
"data": {
"attemptId": "poa_1e6b8f42-9c3d-4a71-b5e8-2f0d6c8a1b34",
"addressType": "COMPANY",
"status": "PENDING",
"createdAt": "2026-07-22T22:00:00.000Z"
}
}Save the attemptId and poll for the review outcome.
Errors
| Status | When |
|---|---|
400 | Invalid JSON or parameters, a document type mismatch, or document submission failed. |
401 | Missing or invalid API key. |
404 | Subaccount, document or attempt not found for your platform. |
409 | Limit increases are not configured for your account. Contact support. |
500 | The optional inline document could not be stored. |
{
"success": false,
"error": "Validation failed",
"details": [{ "field": "addressType", "message": "Invalid enum value" }]
}GET /api/kyb/proof-of-address/{attemptId}
Poll a submitted attempt until it resolves.
Request
curl --request GET \
--url https://api.hodle.com.br/api/kyb/proof-of-address/poa_1e6b8f42-9c3d-4a71-b5e8-2f0d6c8a1b34 \
--header "Authorization: Bearer $API_KEY"const res = await fetch(
`https://api.hodle.com.br/api/kyb/proof-of-address/${attemptId}`,
{ headers: { Authorization: `Bearer ${process.env.HODLE_API_KEY}` } },
)
const data = await res.json()import os, requests
res = requests.get(
f"https://api.hodle.com.br/api/kyb/proof-of-address/{attempt_id}",
headers={"Authorization": f"Bearer {os.environ['HODLE_API_KEY']}"},
)
data = res.json()Response
{
"success": true,
"data": {
"attemptId": "poa_1e6b8f42-9c3d-4a71-b5e8-2f0d6c8a1b34",
"addressType": "COMPANY",
"status": "APPROVED",
"resultMessage": null,
"createdAt": "2026-07-22T22:00:00.000Z",
"updatedAt": "2026-07-22T22:01:43.000Z"
}
}{
"success": true,
"data": {
"attemptId": "poa_1e6b8f42-9c3d-4a71-b5e8-2f0d6c8a1b34",
"addressType": "UBO",
"status": "REJECTED",
"resultMessage": "Document older than 3 months",
"createdAt": "2026-07-22T22:00:00.000Z",
"updatedAt": "2026-07-22T22:01:43.000Z"
}
}Status values
| Status | Meaning |
|---|---|
PENDING | Under review. Keep polling. |
APPROVED | Final: accepted. Limits rise once all three attempts are APPROVED. |
REJECTED | Final: rejected. Read resultMessage, upload a fresh document and resubmit. |
resultMessage explains a rejection and is otherwise null.
Proof of Financial Capacity
Submit the third document through Proof of Financial Capacity, using a statement that covers the requested volume.
Review timing
Review can take hours. Poll each saved attemptId every few minutes; these attempts have no webhook. Confirm KYB is APPROVED before submitting: documents submitted earlier can be accepted for review and rejected later.