Skip to content
/
Identity Document sharing

Identity Document sharing

Request

Share identity documents for KYC verification.

Use Case: Submit customer identity documents directly to Banxa for verification.

Process:

  1. Collect customer information and documents
  2. Submit via this endpoint
  3. Receive 202 Accepted response
  4. Wait for webhook notification with verification result

Required Documents:

  • At least one government-issued photo ID
  • Proof of address (if required)
  • Selfie for liveness verification

Document Quality:

  • Clear, high-resolution images
  • All text readable
  • No glare or shadows
  • Maximum 10MB per image
Security
HMACAuth
Bodyapplication/jsonrequired
identityReferencestring, [ 1 .. 255 ] characters(Identity Reference)^[A-Za-z0-9-]+$required

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
Example:"c-13344"
mobileNumberstring, [ 8 .. 20 ] characters(Mobile Number)^\+[1-9]\d{1,14}$required

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
Example:"+61431000001"
emailstring, (email), <= 254 characters(Email Address)required

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

Example:"[email protected]"
customerIdentityobject(CustomerIdentity)required
occupationIndustrystring(Occupation Industry)required

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.

Enum:"Consulting, IT, or business services""Design, marketing or communication""Travel, accommodation, or transport""Entertainment, arts or photography""Health, sports or personal care""Food, beverages, or tobacco""Retail, eCommerce, wholesale or manufacturing""Dealers & Resellers""Financial services, products, or holding companies""Real estate or construction"
Example:"Consulting, IT, or business services"
occupationstring(Occupation)required

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:

occupationIndustryoccupation
Consulting, IT, or business servicesArchitect
Consulting, IT, or business servicesIT developer
Consulting, IT, or business servicesIT hosting services
Consulting, IT, or business servicesIT consulting/services - other
Consulting, IT, or business servicesScientific or technical consulting
Consulting, IT, or business servicesManagement consulting and coaching
Consulting, IT, or business servicesEmployment placement and recruitment services
Consulting, IT, or business servicesCleaning, repair and maintenance services
Consulting, IT, or business servicesFinancial (inc. tax, accounting, audit)
Consulting, IT, or business servicesLawyer / Legal services
Consulting, IT, or business servicesTranslation or language services
Consulting, IT, or business servicesCompany establishment/formation services
Consulting, IT, or business servicesFreelance platform
Consulting, IT, or business servicesOther consulting
Design, marketing or communicationAdvertising and marketing
Design, marketing or communicationDesigner
Design, marketing or communicationInterior design
Design, marketing or communicationAudio and video
Design, marketing or communicationPhotography
Design, marketing or communicationPrint and online media
Design, marketing or communicationTranslation or language services
Design, marketing or communicationTelecommunications services
Travel, accommodation, or transportTravel agent
Travel, accommodation, or transportTour operator
Travel, accommodation, or transportAccommodation or hotelier
Travel, accommodation, or transportOther travel or tour activities
Travel, accommodation, or transportPassenger transport or rentals
Travel, accommodation, or transportFreight transport
Travel, accommodation, or transportRideshare and transport share services
Travel, accommodation, or transportTransport - other
Entertainment, arts or photographyAudio and video engineer
Entertainment, arts or photographyEvents and entertainment organiser
Entertainment, arts or photographyPhotographer
Entertainment, arts or photographyBooks, magazines, blogs, news
Entertainment, arts or photographyVideo gaming
Entertainment, arts or photographyPerforming arts
Entertainment, arts or photographyGambling, betting, and lotteries
Entertainment, arts or photographyTelecommunications services
Entertainment, arts or photographyAdult Entertainment
Health, sports or personal careBeautician
Health, sports or personal careVitamins and dietary supplements
Health, sports or personal careFitness or sports services
Health, sports or personal careMedical or veterinary services
Health, sports or personal careDental services
Health, sports or personal careMedical equipment
Health, sports or personal careElderly or other care home
Health, sports or personal careNursing or other care services
Health, sports or personal carePharmaceuticals
Health, sports or personal carePharmacy
Food, beverages, or tobaccoFood manufacturing and retail
Food, beverages, or tobaccoRestaurants and catering
Food, beverages, or tobaccoVitamins and dietary supplements
Food, beverages, or tobaccoAlcohol
Food, beverages, or tobaccoSoft drinks
Food, beverages, or tobaccoTobacco
Retail, eCommerce, wholesale or manufacturingClothing and accessories
Retail, eCommerce, wholesale or manufacturingBeauty products and services
Retail, eCommerce, wholesale or manufacturingHome and garden
Retail, eCommerce, wholesale or manufacturingToys, games and musical instruments
Retail, eCommerce, wholesale or manufacturingElectronics and electrical products
Retail, eCommerce, wholesale or manufacturingSports equipment (excl. weapons)
Retail, eCommerce, wholesale or manufacturingManufacturing
Retail, eCommerce, wholesale or manufacturingFarming, seeds, plants
Retail, eCommerce, wholesale or manufacturingPets or pet supplies
Dealers & ResellersVehicle sales
Dealers & ResellersVehicle accessories, spare parts, manufacturing
Dealers & ResellersMachinery and equipment
Dealers & ResellersFirearms, weapons, and military goods/services
Dealers & ResellersArts - fine art sales, auctions or procurement
Dealers & ResellersArts - other arts and crafts products or services
Dealers & ResellersJewellery - fine jewellery, watches
Dealers & ResellersJewellery - fashion jewellery
Dealers & ResellersPrecious stones, diamonds, or metals
Dealers & ResellersChemicals
Dealers & ResellersLegal highs and related accessories
Dealers & ResellersSelling products on behalf of others (incl. auction, online marketplace)
Dealers & ResellersOther retail or wholesale (not listed above)
Financial services, products, or holding companiesFinancial Adviser (inc. tax, accounting, audit)
Financial services, products, or holding companiesInvestment Manager
Financial services, products, or holding companiesMoney service business operator
Financial services, products, or holding companiesProfessional Trader
Financial services, products, or holding companiesInsurance Manager
Financial services, products, or holding companiesCrowdfunding and peer lending
Financial services, products, or holding companiesOther financial services
Real estate or constructionReal estate sale, purchase, and management
Real estate or constructionConstruction
Real estate or constructionReal estate development
Education or learningOnline learning
Education or learningTeaching and tutoring
Education or learningSchools and universities
Charity or not-for-profitAny charity related activity
Public or government servicesGovernment Official
Public or government servicesPolitician
Public or government servicesOther, not listed above
Utility servicesUtility services and providers
Utility servicesCleaning, repair and maintenance services
Utility servicesTelecommunications services
Utility servicesOther, not listed above
Unemployed/RetiredUnemployed/Retired
In between jobs/looking for workIn between jobs/looking for work
Fulltime studentFulltime student
Enum:"Architect""IT developer""IT hosting services""IT consulting/services - other""Scientific or technical consulting""Management consulting and coaching""Employment placement and recruitment services""Cleaning, repair and maintenance services""Financial (inc. tax, accounting, audit)""Lawyer / Legal services"
Example:"IT developer"
sourceOfFundsstring(Source of Funds)required

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
Enum:"Personal Savings""Salary""Business Income/Profits""Pension""Government Benefits""Income from Cryptocurrency Trading""Income from Investments (e.g. shares, bonds, investment funds)""Income from sale of real estate or other property""Income from renting/leasing""Private loan from family members/ friends/others"
Example:"Salary"
purposeOfTransactionstring(Purpose of Transaction)required

The intended purpose for the cryptocurrency transaction.

Compliance Requirement: Required for AML compliance to understand transaction intent.

Note: Currently only 'investment' is supported.

Enum:"Investment""Trading""Payment for Online Purchase""Payment for Services""Gaming""Charity""Ransomware/Virus/Cyber Extortion Demands""Other"
Example:"Investment"
identityDocumentsArray of objects, [ 1 .. 10 ] items(Identity Documents)required

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)
  • Selfie (for liveness verification)

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)
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"
          }
        ]
      },
      {
        "type": "SELFIE",
        "images": [
          {
            "type": "SELFIE",
            "base64": "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
            "mimetype": "image/jpeg"
          }
        ]
      }
    ]
  }'

Responses

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
Bodyapplication/json
identityReferencestring, [ 1 .. 255 ] characters(Identity Reference)^[A-Za-z0-9-]+$required

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
Example:"c-13344"
statusstring(Verification Status)required

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
Enum:"PENDING""UNDER_REVIEW""ACTION_REQUIRED""VERIFIED""REJECTED"
Example:"PENDING"
rejectionReasonobject(Rejection Reason)

Details about why the identity verification was rejected. Only present when status is REJECTED.

customerIdentityobject(CustomerIdentity)
occupationIndustrystring(Occupation Industry)

Echo of the submitted occupation industry.

Example:"Consulting, IT, or business services"
occupationstring(Occupation)

Echo of the submitted occupation.

Example:"IT developer"
purposeOfTransactionstring(Purpose of Transaction)

Submitted transaction purpose.

Enum:"Investment""Trading""Payment for Online Purchase""Payment for Services""Gaming""Charity""Ransomware/Virus/Cyber Extortion Demands""Other"
Example:"Investment"
createdAtstring, (date-time)(Creation Timestamp)

UTC timestamp when the identity verification request was created.

Format: ISO 8601 date-time format

Example:"2023-06-05T19:53:08.320Z"
Response
{
  "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"
}
© Banxa 2026