Retrieve a customer
Retrieves a single customer by its ozav_cus_ id, including its current status, verification posture, and outstanding requirements. An id that does not exist or belongs to another organization returns 404.
Request
- Base URLhttps://developers.ozav.io/v2
- Auth
- API key in header X-API-Key
- or HTTP bearer
Response
The customer.
Opaque customer identifier, prefixed ozav_cus_.
Resource type discriminator; always the literal customer.
Whether the customer is a natural person (individual) or a company (business).
Onboarding / KYC lifecycle state of a customer.
| Value | Meaning |
|---|---|
| pending | Created; verification has not completed. The customer cannot transact yet. |
| in_review | Checks were submitted and are under (automated or manual) review. |
| approved | Verification passed. The customer may transact once OZAV has everything a payout will need; see the note below. |
| rejected | Verification failed; the customer cannot be onboarded. |
| suspended | A previously active customer has been blocked by a compliance or operational action. |
approved is about the checks, not about being able to operate. OZAV activates a customer only when it also holds everything a payout will need: the holder's name, a valid tax document for the country declared on it, and an address. A Brazilian company with a valid CNPJ is exempt from the address, because the public registry supplies it.
A customer can therefore sit at approved and still be refused, with 422 on POST /accounts and on the money paths. The gap shows up there, before any funds are committed, and not at payout time.
The request body cannot resolve it. Send the missing field through the customer update path, or ask OZAV: the blocked queue names each customer and the exact field it is waiting on.
Whether the account can operate - a different question from whether the verification passed, which is status. active means named accounts, cards and payouts are available. pending means they are not, and the calls that need them refuse with 422 ACCOUNT_NOT_ACTIVATED. An approved customer can sit at pending for two different reasons. When data is missing, requirements.due names it and requirements.owner reads integrator - send the field with PATCH /customers/{customer_id} and the account activates in the same response. When due is empty, the account is simply not provisioned yet and nothing is owed by you. Read this field instead of inferring operability from status: an approved customer is not necessarily one that can move money.
Your own identifier for this customer, as supplied at creation.
Contact email for the customer.
Contact phone number (E.164).
When the customer was created (RFC 3339 / ISO 8601, UTC).
When the customer was last modified (RFC 3339 / ISO 8601, UTC).
Free-form string map (max 50 keys).
The documents this customer will need before an account can be opened for them, given their type and country of registration. Returned on POST /customers so you learn the list when the customer is created, not when the account is refused.
This is not requirements.documents_due, and the difference matters. documents_due is what OZAV has formally asked for, each item with a deadline and a reason; right after creation it is empty, because nothing has been asked yet. still_required is what the corridor will demand regardless - a Brazilian company needs seven documents (plus four per associated person, reported by GET /customers/{customer_id}/documents in still_required_by_person) whether or not anyone has asked.
Absent, never [], for a customer whose requirement set is not modelled: an empty list would assert "nothing is missing", and that promise is only safe to make for the shapes the gate actually models. The same field, computed the same way, is returned by GET /customers/{customer_id}/documents once documents start arriving.
Example response
{
"business": {
"cnae_codes": [
"6201-5/01"
]
}
}Changes
No recorded changes to this operation across all 1 revision of this API.