KYB fields

Every field of the KYB document, its accepted values, the document slots, and how to read a missing[] path.

Every field of the KYB document, with its accepted values. The document is the body of PUT /dapi/v1/client/kyb and the document block of GET /dapi/v1/client/kyb; both use the same shape, and both take the client id in X-Hevn-Account rather than in a path. Onboarding is the flow that fills it.

“Required” below means completion is refused without it — the field appears in missing[] until it is set. Everything under “Optional detail” is accepted, never demanded by the gate, and routinely asked for by a reviewer instead: sending what you already hold is how an RFI is avoided rather than answered.

company

Field	Type	Required	Notes
legalName	string, 1–200	yes	The registered name. Unique across HEVN; it is also the client’s account name.
tradeName	string, 1–200	no	The name the business trades under, if different.
country	ISO 3166-1 alpha-2	yes	The jurisdiction of incorporation. Widens the required document slots.
registrationNumber	string, 1–200	no	The company number in its own register.
taxId	string, 1–200	US only	A US company owes its EIN as XX-XXXXXXX. A value that is not in that shape counts as missing.
phone	E.164	yes	Satisfied by the account phone as well — see onboarding.
email	string, 1–200	no	A compliance mailbox. HEVN does not write to it.
address	object	yes	See below.
entityType	enum	yes
incorporationDate	YYYY-MM-DD	no
websites	array of strings	no
expectedMonthlyVolumeUsd	decimal string, ≥ 0	yes	Major units, for example "250000".
businessDescription	string, 1–4000	yes	What the company sells, in a sentence a reviewer can act on.
businessType	enum	yes
businessIndustry	6 digits	no	An industry classification code, for example "424990".
verifierRole	enum	no	The relationship of the person who filled this in to the company.
sourceOfFunds	enum	yes	Where the money the client will move comes from.
purposeOfFunds	enum	yes	What it will be used for.
flowOfFunds	string, 1–4000	yes	How money reaches the company and where it goes, in plain sentences.

company — optional detail

None of these appears in missing[]. All of them are read by a reviewer.

Field	Type	Notes
entityTypeDescription	string, 1–200	The legal form in words, when entityType is other.
industry	string, 1–200	The industry in words, alongside the businessIndustry code.
businessTypeDetails	string, 1–4000	What businessType does not capture.
productsServices	array of strings, 1–200 each	What the company sells, itemised.
linkedinUrl	string, 1–2000	The company’s public LinkedIn page.
operatingCountries	array of ISO 3166-1 alpha-2	Where it trades, as distinct from where it is registered.
primaryTargetMarket	enum	Who it sells to.
publicListed	boolean	Whether the company is listed.
institutionalInvestors	boolean	Whether institutional investors fund or own it.
isRegulated	boolean	Whether it holds a licence or sits under a regulator.
estimatedAnnualRevenue	decimal, ≥ 0	Annual revenue in USD.
revenueCovers	enum	How much of operating expense that revenue covers.
txPerMonth	enum	Expected transaction count per month.
expectedCryptoMonthlyVolumeUsd	decimal, ≥ 0	The digital-asset share of expectedMonthlyVolumeUsd.
expectedMonthlyAchUsd	decimal, ≥ 0	The ACH share.
expectedMonthlyWireUsd	decimal, ≥ 0	The wire share.
depositMethods	array of strings, 1–200 each	How and from where the account will be funded.
usesBlockchain	boolean	Whether blockchain or digital assets are used in operations.
cryptoIndustrySubtype	enum	The digital-asset business model, when there is one.
hasUsBank	boolean	Whether the company already holds a US payment account.
deniedUsBank	boolean	Whether a US institution has declined or closed one.
hasIntermediateEntityOwnership	boolean	Whether another legal entity sits between the company and a beneficial owner. See complex ownership.
hasPep	boolean	Whether the company, an owner or a controller is a politically exposed person.
bizAdverse	array of strings, 1–4000 each	Adverse information about the company, declared up front.
ownersAdverse	array of strings, 1–4000 each	The same for its owners and controllers.
sanctionedCountryOperations	boolean	Whether it operates in or serves sanctioned jurisdictions.
highRiskActivities	array of enum	Higher-risk activities it performs.
handlesCustomerFunds	boolean	Whether it receives, holds or transfers funds for its own customers.
actingAsIntermediary	boolean	Whether it sits between the payer and the ultimate beneficiary.
moneyServicesDescription	string, 1–4000	The money-services activity, when there is any.
complianceScreening	string, 1–4000	How it screens its own customers and transactions.
sourceOfFundsDetails	string, 1–4000	The sourceOfFunds answer, explained.
purposeOfFundsDetails	string, 1–4000	The purposeOfFunds answer, explained.
contactInfo	string, 1–4000	Any further contact or operational detail.
identityDocuments	array of {type, number, issuingCountry}	Identification issued to the company, where the jurisdiction issues any. Metadata only — see below.

identityDocuments

Both company and people[] take this array. It carries the metadata off an identity document; the file itself is still a POST /dapi/v1/documents upload filed into a documents[] slot, and neither replaces the other.

Field	Type
type	enum
number	string, 1–200, exactly as printed
issuingCountry	ISO 3166-1 alpha-2

company.address and people[].address

Both addresses take the same object. Four of its fields are required; state and addressLine2 are not.

Field	Type	Required
streetAddress	string, 1–200	yes
addressLine2	string, 1–200	no
city	string, 1–200	yes
state	string, 1–200	no
zip	string, 1–200	yes
country	ISO 3166-1 alpha-2	yes

Write state as the ISO 3166-2 subdivision including its country prefix — US-IL, not IL and not Illinois.

people[]

At least one person is required: a document with an empty roster reports people as missing. Give each person at least one role — ownershipPercentage, hasControl, isDirector or isSigner — or they are in the graph without being anything in it.

Field	Type	Required	Notes
key	1–64 of A-Z a-z 0-9 . _ : -	key or id	Your own stable handle for this person. HEVN derives their id from it, which is what makes the write idempotent.
id	UUID	key or id	Addresses a person who already exists in the client’s graph. Takes precedence over key. A person with neither is refused.
firstName	string, 1–200	no
middleName	string, 1–200	no
lastName	string, 1–200	no
dateOfBirth	YYYY-MM-DD	no
email	string, 1–200	no
phone	E.164	yes
address	object	yes
taxIdCountry	ISO 3166-1 alpha-2	yes	The country whose tax authority holds this person’s number. Declared, never derived from the address.
taxId	string, 1–200	US only	A US tax resident owes an SSN as XXX-XX-XXXX.
ownershipPercentage	decimal string, > 0 and ≤ 100	no
hasControl	boolean	no
isDirector	boolean	no
isSigner	boolean	no
documents	array of {slot, uploadId}	yes	One proof_of_address per person.

These six are optional and, like the company’s, are read rather than demanded:

Field	Type	Notes
title	string, 1–200	The office held, for example Director.
birthCountry	ISO 3166-1 alpha-2	Country of birth.
nationalities	array of ISO 3166-1 alpha-2	Every nationality held.
country	ISO 3166-1 alpha-2	Country of residence. Distinct from taxIdCountry, which is declared, and from address.country.
linkedinUrl	string, 1–2000	The person’s public LinkedIn profile.
identityDocuments	array of {type, number, issuingCountry}	Passport or ID metadata, as above.

Enums

Send one of the listed members. An unlisted value is refused at the boundary with 422 invalid_enum_value, carrying details.field and the accepted set in details.allowed — nothing is written.

entityType

llc · corporation · s_corporation · c_corporation · partnership · limited_partnership · sole_proprietorship · nonprofit · trust · cooperative · dao · foundation · other

businessType

technology · finance · healthcare · retail · e_commerce · manufacturing · real_estate · consulting · hospitality · education · transportation · entertainment · agriculture · construction · professional_services · crypto_web3 · other

sourceOfFunds

business_revenue · investment · loan · personal_savings · third_party_funds · grant · other

purposeOfFunds

operations · payroll · vendor_payments · investment · treasury_management · international_transfers · other

verifierRole

officer · employer · accountant · agent

cryptoIndustrySubtype

protocol · exchange · investment · lender · market_maker · saas · miner

primaryTargetMarket

retail · commercial · government · other

revenueCovers

all_operating_expenses · most · some · minimal

txPerMonth

<10 · 10-50 · 50-200 · 200-1,000 · 1,000+

These members are not identifiers. Send them exactly as printed, punctuation included.

highRiskActivities

MONEY_SERVICES · LENDING_BANKING · OTC_FX_CRYPTO_BROKERAGE · HOLD_CLIENT_FUNDS · INVESTMENT_SERVICES · SAFE_DEPOSIT_BOX · PRECIOUS_METALS_STONES_JEWELRY · NICOTINE_TOBACCO · MARIJUANA · PHARMACEUTICALS · THIRD_PARTY_PAYMENT_PROCESSING · ADULT_ENTERTAINMENT · WEAPONS_FIREARMS_EXPLOSIVES · GAMBLING

The one upper-case enum in the API.

identityDocuments[].type

passport · id_card · drivers_license · driver_license · residence_permit · government_id · state_or_provincial_id · visa

Two of these break the snake_case rule the rest of the API keeps: highRiskActivities is upper-case and txPerMonth carries digits and punctuation. Match them character for character.

Document slots

A slot is a named place a document goes. You upload a file, get a doc_… id back, and file it into a slot with {"slot": "...", "uploadId": "doc_..."} — on the document’s own documents[] for company papers, on a person’s documents[] for theirs.

Every client needs these five on the company:

Slot	What it is
certificate_of_incorporation	The registrar’s proof the company exists.
corporate_structure	The ownership chart, down to the people.
director_structure	Who the directors are.
proof_of_address	A recent document showing the company’s registered address.
source_of_funds	Evidence behind the sourceOfFunds answer.

The jurisdiction adds to that list:

company.country	Extra slot
US	tax_identification_document — the IRS letter that assigned the EIN.
AE	vat_registration — the FTA VAT/TRN registration certificate.

And every person needs one:

Slot	What it is
proof_of_address	A recent document showing where that person lives.

Other slots exist and are accepted — passport_front, national_id, articles_of_association, bank_statement, ubo_declaration, power_of_attorney and more — and a reviewer may ask for one in an RFI. Send an unknown slot and the write answers 422 document_type_unsupported with the full accepted list in details.allowed.

Reading a missing[] path

Every entry is a path into the document you sent. Fix it there and write again.

Path	Means
company.flowOfFunds	A company field is empty.
company.address.zip	A required address field is empty.
people	The roster is empty. Add at least one person.
people[0].taxIdCountry	A field on the first person in the document is empty.
people[0].documents.proof_of_address	That person’s slot has nothing in it.
documents.certificate_of_incorporation	A company slot has nothing in it.
graph.entities.<uuid>.phone	The gap belongs to an entity the flat document does not own.

The index in people[0] is the person’s position in the people array of GET /dapi/v1/client/kyb, not the order you happened to send. Read the document back and index into that.

Complex ownership

The flat document models one company owned directly by people; hasIntermediateEntityOwnership is where you declare that it does not. A chain with holding companies in it is written through HEVN’s entity-graph routes, which are outside this API and available on request. The two models coexist: the flat document only ever replaces the people it created, and never touches an entity added another way — a write that would drop one answers 409 kyb_roster_conflict with details.entityIds. Gaps belonging to those entities are the graph.entities.<uuid>.<field> rows above.

Next: Errors

The envelope, and every slug the API can answer with.