Share identity documents for KYC verification.
Use Case: Submit customer identity documents directly to Banxa for verification.
Process:
- Collect customer information and documents
- Submit via this endpoint
- Receive 202 Accepted response
- Wait for webhook notification with verification result
Required Documents:
- At least one government-issued photo ID
- Proof of address (if required)
A liveness check cannot be uploaded as a document. It is completed through Sumsub token sharing or a Banxa-hosted flow.
Document Quality:
- Clear, high-resolution images
- All text readable
- No glare or shadows
- Maximum 10MB per image
Requires KYC sharing: KYC sharing must be enabled for your account. If it isn't, this endpoint returns 400 with code 4005 and the message "KYC sharing not enabled". Contact your Banxa integration manager to enable it.
A unique customer identifier provided by the partner. This field is required and must be unique for each customer.
Important: You must consistently reuse the same identityReference for repeat interactions with the same customer, allowing Banxa to reliably recognize and associate their identity across multiple transactions.
Format Requirements:
- Only ASCII letters (a-z, A-Z), digits (0-9), and hyphens (-) are allowed
- Must be between 1 and 255 characters
- Case-sensitive
Best Practices:
- Use a consistent format across your system
- Consider using a prefix to identify your organization (e.g., 'partner-customer-123')
- Do not include personally identifiable information (PII) in the reference
- Store the mapping between your internal customer ID and this reference securely
Customer's mobile phone number in international format (E.164).
Format: Include country code with + prefix
Examples:
- "+61431000001" (Australia)
- "+14155552671" (USA)
- "+442071234567" (UK)
Requirements:
- Must be a valid, active mobile number
- Used for SMS verification if needed
- Maximum 20 characters
Customer's email address.
Requirements:
- Must be a valid email format
- Used for communication and verification
- Maximum 254 characters (RFC 5321)
Best Practice: Use the customer's primary email address
The industry sector of the customer's occupation.
Important: The selected industry determines which specific occupations are valid. See the Occupation schema for the mapping table.
Compliance Requirement: Required for AML/KYC compliance to assess customer risk profile.
Customer's occupation. Must be a valid occupation for the selected 'occupationIndustry'. When the selected combination is invalid a validation error will be thrown. Refer to the Occupation-Industry mapping table:
| occupationIndustry | occupation |
|---|---|
| Consulting, IT, or business services | Architect |
| Consulting, IT, or business services | IT developer |
| Consulting, IT, or business services | IT hosting services |
| Consulting, IT, or business services | IT consulting/services - other |
| Consulting, IT, or business services | Scientific or technical consulting |
| Consulting, IT, or business services | Management consulting and coaching |
| Consulting, IT, or business services | Employment placement and recruitment services |
| Consulting, IT, or business services | Cleaning, repair and maintenance services |
| Consulting, IT, or business services | Financial (inc. tax, accounting, audit) |
| Consulting, IT, or business services | Lawyer / Legal services |
| Consulting, IT, or business services | Translation or language services |
| Consulting, IT, or business services | Company establishment/formation services |
| Consulting, IT, or business services | Freelance platform |
| Consulting, IT, or business services | Other consulting |
| Design, marketing or communication | Advertising and marketing |
| Design, marketing or communication | Designer |
| Design, marketing or communication | Interior design |
| Design, marketing or communication | Audio and video |
| Design, marketing or communication | Photography |
| Design, marketing or communication | Print and online media |
| Design, marketing or communication | Translation or language services |
| Design, marketing or communication | Telecommunications services |
| Travel, accommodation, or transport | Travel agent |
| Travel, accommodation, or transport | Tour operator |
| Travel, accommodation, or transport | Accommodation or hotelier |
| Travel, accommodation, or transport | Other travel or tour activities |
| Travel, accommodation, or transport | Passenger transport or rentals |
| Travel, accommodation, or transport | Freight transport |
| Travel, accommodation, or transport | Rideshare and transport share services |
| Travel, accommodation, or transport | Transport - other |
| Entertainment, arts or photography | Audio and video engineer |
| Entertainment, arts or photography | Events and entertainment organiser |
| Entertainment, arts or photography | Photographer |
| Entertainment, arts or photography | Books, magazines, blogs, news |
| Entertainment, arts or photography | Video gaming |
| Entertainment, arts or photography | Performing arts |
| Entertainment, arts or photography | Gambling, betting, and lotteries |
| Entertainment, arts or photography | Telecommunications services |
| Entertainment, arts or photography | Adult Entertainment |
| Health, sports or personal care | Beautician |
| Health, sports or personal care | Vitamins and dietary supplements |
| Health, sports or personal care | Fitness or sports services |
| Health, sports or personal care | Medical or veterinary services |
| Health, sports or personal care | Dental services |
| Health, sports or personal care | Medical equipment |
| Health, sports or personal care | Elderly or other care home |
| Health, sports or personal care | Nursing or other care services |
| Health, sports or personal care | Pharmaceuticals |
| Health, sports or personal care | Pharmacy |
| Food, beverages, or tobacco | Food manufacturing and retail |
| Food, beverages, or tobacco | Restaurants and catering |
| Food, beverages, or tobacco | Vitamins and dietary supplements |
| Food, beverages, or tobacco | Alcohol |
| Food, beverages, or tobacco | Soft drinks |
| Food, beverages, or tobacco | Tobacco |
| Retail, eCommerce, wholesale or manufacturing | Clothing and accessories |
| Retail, eCommerce, wholesale or manufacturing | Beauty products and services |
| Retail, eCommerce, wholesale or manufacturing | Home and garden |
| Retail, eCommerce, wholesale or manufacturing | Toys, games and musical instruments |
| Retail, eCommerce, wholesale or manufacturing | Electronics and electrical products |
| Retail, eCommerce, wholesale or manufacturing | Sports equipment (excl. weapons) |
| Retail, eCommerce, wholesale or manufacturing | Manufacturing |
| Retail, eCommerce, wholesale or manufacturing | Farming, seeds, plants |
| Retail, eCommerce, wholesale or manufacturing | Pets or pet supplies |
| Dealers & Resellers | Vehicle sales |
| Dealers & Resellers | Vehicle accessories, spare parts, manufacturing |
| Dealers & Resellers | Machinery and equipment |
| Dealers & Resellers | Firearms, weapons, and military goods/services |
| Dealers & Resellers | Arts - fine art sales, auctions or procurement |
| Dealers & Resellers | Arts - other arts and crafts products or services |
| Dealers & Resellers | Jewellery - fine jewellery, watches |
| Dealers & Resellers | Jewellery - fashion jewellery |
| Dealers & Resellers | Precious stones, diamonds, or metals |
| Dealers & Resellers | Chemicals |
| Dealers & Resellers | Legal highs and related accessories |
| Dealers & Resellers | Selling products on behalf of others (incl. auction, online marketplace) |
| Dealers & Resellers | Other retail or wholesale (not listed above) |
| Financial services, products, or holding companies | Financial Adviser (inc. tax, accounting, audit) |
| Financial services, products, or holding companies | Investment Manager |
| Financial services, products, or holding companies | Money service business operator |
| Financial services, products, or holding companies | Professional Trader |
| Financial services, products, or holding companies | Insurance Manager |
| Financial services, products, or holding companies | Crowdfunding and peer lending |
| Financial services, products, or holding companies | Other financial services |
| Real estate or construction | Real estate sale, purchase, and management |
| Real estate or construction | Construction |
| Real estate or construction | Real estate development |
| Education or learning | Online learning |
| Education or learning | Teaching and tutoring |
| Education or learning | Schools and universities |
| Charity or not-for-profit | Any charity related activity |
| Public or government services | Government Official |
| Public or government services | Politician |
| Public or government services | Other, not listed above |
| Utility services | Utility services and providers |
| Utility services | Cleaning, repair and maintenance services |
| Utility services | Telecommunications services |
| Utility services | Other, not listed above |
| Unemployed/Retired | Unemployed/Retired |
| In between jobs/looking for work | In between jobs/looking for work |
| Fulltime student | Fulltime student |
The source from which the customer's funds are obtained.
Compliance Requirement: Required for AML compliance to verify the origin of funds.
Common Sources:
- Employment income (Salary)
- Business revenue (Business Income/Profits)
- Investment returns
- Savings and inheritance
The intended purpose for the cryptocurrency transaction.
Compliance Requirement: Required for AML compliance to understand transaction intent.
Note: Currently only 'investment' is supported.
Array of identity documents to verify the customer's identity.
Minimum Requirements:
- At least one government-issued photo ID (Passport, Driver's License, or National ID)
- Proof of Address (if required based on jurisdiction)
A liveness check cannot be uploaded as a document. It is completed through Sumsub token sharing or a Banxa-hosted flow.
Document Quality Requirements:
- Clear, high-resolution images
- All text must be readable
- All four corners of the document visible
- No glare or shadows obscuring information
- Color images preferred
- Maximum file size: 10MB per image (before base64 encoding)
- Mock serverhttps://docs.banxa.com/_mock/products/native-api/openapi/eapi/v0/identities/share/documents
- Production environment serverhttps://api.banxa.com/eapi/v0/identities/share/documents
- Sandbox environment serverhttps://api.banxa-sandbox.com/eapi/v0/identities/share/documents
Example of a complete identity verification submission including a passport and proof of address
curl -i -X POST \
https://docs.banxa.com/_mock/products/native-api/openapi/eapi/v0/identities/share/documents \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"identityReference": "customer-12345",
"mobileNumber": "+61431000001",
"email": "[email protected]",
"customerIdentity": {
"givenName": "John",
"surname": "Doe",
"dob": "1990-01-15",
"residentialAddress": {
"addressLine": "123 Main Street",
"suburb": "Sydney",
"state": "NSW",
"postCode": "2000",
"country": "AU"
}
},
"occupationIndustry": "Consulting, IT, or business services",
"occupation": "IT developer",
"sourceOfFunds": "Salary",
"purposeOfTransaction": "Investment",
"identityDocuments": [
{
"type": "PASSPORT",
"data": {
"number": "N1234567"
},
"images": [
{
"type": "PASSPORT",
"base64": "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"mimetype": "image/jpeg"
}
]
},
{
"type": "PROOF_OF_ADDRESS",
"images": [
{
"type": "PROOF_OF_ADDRESS",
"base64": "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"mimetype": "image/jpeg"
}
]
}
]
}'The identity document sharing request has been accepted for processing, but the processing of the sent documents has not been finished yet.
Next Steps:
- Documents are being verified (typical time: 1-24 hours)
- You will receive a webhook notification when verification is complete
- Status will be either VERIFIED or REJECTED
A unique customer identifier provided by the partner. This field is required and must be unique for each customer.
Important: You must consistently reuse the same identityReference for repeat interactions with the same customer, allowing Banxa to reliably recognize and associate their identity across multiple transactions.
Format Requirements:
- Only ASCII letters (a-z, A-Z), digits (0-9), and hyphens (-) are allowed
- Must be between 1 and 255 characters
- Case-sensitive
Best Practices:
- Use a consistent format across your system
- Consider using a prefix to identify your organization (e.g., 'partner-customer-123')
- Do not include personally identifiable information (PII) in the reference
- Store the mapping between your internal customer ID and this reference securely
Current status of the identity verification.
Status Meanings:
- PENDING: Documents are being reviewed (typical review time: 1-24 hours)
- VERIFIED: Identity verified successfully, customer can transact
- REJECTED: Documents rejected, see rejectionReason for details
Details about why the identity verification was rejected. Only present when status is REJECTED.
Echo of the submitted occupation industry.
Submitted transaction purpose.
{ "identityReference": "customer-12345", "status": "PENDING", "customerIdentity": { "givenName": "John", "surname": "Doe", "dob": "1990-01-15", "residentialAddress": { … } }, "occupationIndustry": "Consulting, IT, or business services", "occupation": "IT developer", "purposeOfTransaction": "Investment", "createdAt": "2023-06-05T19:53:08.320Z" }