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:

DocumentdocumentTypeProvesSubmit with
Company addressPROOF-OF-ADDRESS-COMPANYThe registered business addressPOST /api/kyb/proof-of-address · addressType: "COMPANY"
UBO addressPROOF-OF-ADDRESSThe Ultimate Beneficial Owner's residencePOST /api/kyb/proof-of-address · addressType: "UBO"
Financial capacityPROOF-OF-FINANCIAL-CAPACITYThat the company's funds or income back the declared volumePOST /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 document copy.
  • Third-party issued and legible, with the holder's name matching the KYB data.

Flow

  1. Confirm the COMPANY subaccount's KYB is APPROVED.
  2. Company address — register a PROOF-OF-ADDRESS-COMPANY document, PUT the PDF, poll until ready: true, then submit it with addressType: "COMPANY".
  3. UBO address — register a PROOF-OF-ADDRESS document, PUT the PDF, poll until ready: true, then submit it with addressType: "UBO".
  4. Financial capacity — register a PROOF-OF-FINANCIAL-CAPACITY document, PUT the PDF, poll until ready: true, then submit it to POST /api/kyb/proof-of-financial-capacity.
  5. Poll each of the three attemptIds until status: 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" }'
FieldTypeRequiredDescription
subAccountIdstringYesThe COMPANY subaccount the document belongs to.
documentTypestringYesPROOF-OF-ADDRESS-COMPANY (company address) or PROOF-OF-ADDRESS (UBO residence).
201 Created
{
  "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"
200 OK
{ "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

FieldTypeRequiredDescription
subAccountIdstringYesThe COMPANY subaccount's id.
uploadedPoAIdstringYesdocumentId of the uploaded Proof of Address PDF, with ready: true.
addressTypestringYesCOMPANY for the company address, UBO for the beneficial owner's residence.
desiredMonthlyLimitintegerNoPositive 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.
documentstringNoOptional base64 PDF copy, up to ~10 MB of binary. The uploaded document ID identifies the document reviewed.
documentMimeTypestringNoMIME type of document, e.g. application/pdf.

Response

202 Accepted
{
  "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

StatusWhen
400Invalid JSON or parameters, a document type mismatch, or document submission failed.
401Missing or invalid API key.
404Subaccount, document or attempt not found for your platform.
409Limit increases are not configured for your account. Contact support.
500The optional inline document could not be stored.
400 — validation failed
{
  "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

status: APPROVED
{
  "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"
  }
}
status: REJECTED
{
  "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

StatusMeaning
PENDINGUnder review. Keep polling.
APPROVEDFinal: accepted. Limits rise once all three attempts are APPROVED.
REJECTEDFinal: 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.