Customers

Upload supporting-document bytes

Uploads file bytes to the short-lived OZAV-hosted upload_url returned by POST /customers/{customer_id}/documents. Send the same API key used to create the grant. OZAV stores the file in private storage, recomputes size and SHA-256 server-side, and moves the document to received when the bytes are accepted.

put/customers/{customer_id}/documents/{document_id}/upload

Request

  • Base URL
    https://developers.ozav.io/v2
  • Auth
    • API key in header X-API-Key
    • or HTTP bearer

Query parameters

upload_tokenstring required

Short-lived upload token embedded in the upload_url.

Request body application/pdf

string binary required

Response

Document bytes accepted and the document is marked received.

idstring

Opaque document id.

object'document'

Resource type discriminator; always the literal document.

customer_idstring

The customer this document belongs to.

subject_type'customer' | 'associated_person'

Whose document this is. customer - the customer itself. associated_person - one of a business customer's associated persons, named in associated_person_id.

associated_person_idstring

Present when subject_type is associated_person.

doc_type'identity_document' | 'selfie' | 'liveness' | 'proof_of_address' | 'company_registration' | 'ownership_structure' | 'financial_statement' | 'source_of_funds' | 'bank_statement' | 'authorized_signature_form' | 'banking_reference' | 'corporate_resolution' | 'good_standing_certificate' | 'source_of_funds_certification' | 'tax_registration' | 'pep_declaration' | 'income_tax_return' | 'other'

The kind of KYC/KYB document. Jurisdiction-agnostic - generic categories, never country-specific artifact names - because this API onboards your customers worldwide.

What this list is, and what it is not. It is the vocabulary for declaring what you are uploading. It is not a per-country list of which artifact satisfies which category: whether a given national ID, driving licence or utility bill is accepted for a specific customer is decided in review, not by this enum, and OZAV does not publish a per-jurisdiction acceptance table. Declare the category that best describes the artifact and upload it; if something is missing or unusable you get a named outcome on the verification, not a silent rejection.

The fields a customer must supply are a separate question, answered by requirements.missing_fields on the customer itself. That set is driven by the country on tax_id / registration, and it does not vary by the currency of any account you later open.

Required versus optional, and why nothing here blocks. For an international account the receiving institution asks for a defined set of company information. Some categories below satisfy part of that set and some do not apply to every company - a Brazilian company, for example, has no separate memorandum of association, because its Contrato Social is both the constitutive act and the articles.

So this API accepts every category at any time and refuses none of them for being absent. Upload what the company has, under the category that describes it.

What this API does not do yet, said plainly. requirements on GET /customers/{id} reports missing onboarding fields, not missing documents - it will not tell you which of the categories above are still outstanding. Document review happens at the receiving institution, and today its outcome reaches you through your account contact, not through this API. Publishing the list here without saying that would suggest a completeness signal that does not exist.

A company that cannot produce one of these is not blocked from being created. It is blocked, later and visibly, from having an account opened - and the difference matters: the first is a wall at the door, the second is a list you can work through.

Three categories for the Brazilian named account. tax_registration is the company's tax registration certificate (in Brazil, the Cartão CNPJ). pep_declaration is a politically-exposed-person declaration, one per partner or legal representative (subject_type: associated_person), optional except for a BRL account. income_tax_return is the company's income tax return, accepted as evidence of economic capacity alongside financial_statement. A bank statement is not accepted as economic capacity by the Brazilian receiving institution; send a balance sheet or the tax return instead.

side'front' | 'back' | 'single' | 'null' nullable

Which face of a two-sided document these bytes are. single for a document captured in one image. null where the document type has no sides (a PDF statement).

issuing_countrystring nullable

ISO 3166-1 alpha-2 country that issued the document, when known. null when the document type has no issuer (a proof of address) or it was not supplied.

status'pending_upload' | 'received' | 'rejected'

pending_upload = grant issued, bytes not yet confirmed; received = bytes present; rejected = failed review.

mimestring nullable

Content type of the stored bytes, as observed on upload. null while status is pending_upload.

size_bytesinteger nullable

Size of the stored bytes. null while status is pending_upload.

sha256string nullable

SHA-256 of the stored bytes, computed by OZAV on receipt - not a value you send. Compare it against your own digest to prove the upload was not truncated. null while status is pending_upload.

created_atstring date-time

When the upload grant was created (RFC 3339, UTC), not when bytes arrived.

updated_atstring date-time

When the record last changed (RFC 3339, UTC) - the receipt of bytes and a review outcome both move it.

Example response

{
  "id": "ozav_doc_01J8Z9K2M3N4P5Q6R7S8T9U0V1"
}

Changes

No recorded changes to this operation across all 1 revision of this API.