# Identity Document sharing

Share identity documents

Endpoint: POST /eapi/v0/identities/share/documents
Version: 0 BETA
Security: HMACAuth

## Request fields (application/json):

  - `identityReference` (string, required)
    ASCII letters, digits, and hyphen only, A unique customer identifier provided by you. This field is required and must be unique for each customer. Please ensure you consistently reuse the same identityReference for repeat interactions with the same customer, allowing us to reliably recognize and associate their identity.
    Example: "c-13344"

  - `mobileNumber` (string, required)
    Mobile (msisdn) number of the customer.
    Example: "+61431000001"

  - `email` (string, required)
    Email address of the customer.
    Example: "test@bitcoin.com.au"

  - `customerIdentity` (object, required)

  - `customerIdentity.givenName` (string, required)
    Customer's given / first name.
    Example: "Joe"

  - `customerIdentity.surname` (string, required)
    Customer's surname / last name.
    Example: "Bloggs"

  - `customerIdentity.dob` (string, required)
    Customer's date of birth (e.g. "1985-01-31"). Required to format as ISO 8601 Date format : YYYY-MM-DD.
    Example: "1990-01-31"

  - `customerIdentity.taxIdType` (string)
    Tax identification number (e.g. SSN). Optional unless required (e.g. for US). This is the national identifier for the customer, for example, the customer's Social Security number (SSN) in the US.  Must be a nine-digit number in the format "AAA-GG-SSSS".
    Example: "ssn"

  - `customerIdentity.taxId` (string)
    Tax identification number (e.g. SSN). Optional unless required (e.g. for US). This is the national identifier for the customer, for example, the customer's Social Security number (SSN) in the US.  Must be a nine-digit number in the format "AAA-GG-SSSS".
    Example: "123-11-123"

  - `customerIdentity.taxState` (string)
    Tax state or region if applicable.(associated with the taxId) Required format as two characters. Note; We do not accept any states where Banxa is not licensed.
    Example: "IL"

  - `customerIdentity.residentialAddress` (object, required)

  - `customerIdentity.residentialAddress.addressLine` (string, required)
    Street address.
    Example: "44 Gwynne Street"

  - `customerIdentity.residentialAddress.suburb` (string, required)
    Suburb of the address.
    Example: "Cremorne"

  - `customerIdentity.residentialAddress.state` (string, required)
    State or region, required when country is US.
    Example: "VIC"

  - `customerIdentity.residentialAddress.postCode` (string, required)
    Postal code.
    Example: "3121"

  - `customerIdentity.residentialAddress.country` (string, required)
    Country code.
    Example: "AU"

  - `occupationIndustry` (string, required)
    Industry related to the customer's occupation.
The valid values for 'occupation' depend on the selected 'occupationIndustry'.
For example, if 'occupationIndustry' is 'Consulting, IT, or business services', only certain occupations are valid.
Refer to the Occupation-Industry mapping table in the API documentation for allowed combinations.
This relationship is strictly enforced by server-side validation.
    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", "Education or learning", "Charity or not-for-profit", "Public or government services", "Utility services", "Unemployed/Retired", "In between jobs/looking for work", "Fulltime student"

  - `occupation` (string, 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:
| 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 |
    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", "Translation or language services", "Company establishment/formation services", "Freelance platform", "Other consulting", "Advertising and marketing", "Designer", "Interior design", "Audio and video", "Photography", "Print and online media", "Telecommunications services", "Travel agent", "Tour operator", "Accommodation or hotelier", "Other travel or tour activities", "Passenger transport or rentals", "Freight transport", "Rideshare and transport share services", "Transport - other", "Audio and video engineer", "Events and entertainment organiser", "Photographer", "Books, magazines, blogs, news", "Video gaming", "Performing arts", "Gambling, betting, and lotteries", "Adult Entertainment", "Beautician", "Vitamins and dietary supplements", "Fitness or sports services", "Medical or veterinary services", "Dental services", "Medical equipment", "Elderly or other care home", "Nursing or other care services", "Pharmaceuticals", "Pharmacy", "Food manufacturing and retail", "Restaurants and catering", "Alcohol", "Soft drinks", "Tobacco", "Clothing and accessories", "Beauty products and services", "Home and garden", "Toys, games, musical instruments", "Electronics and electrical products", "Sports equipment", "Manufacturing", "Farming, seeds, plants", "Pets and pet supplies", "Vehicle sales", "Vehicle accessories, parts, manufacturing", "Machinery and equipment", "Firearms, weapons, military", "Arts, fine art sales", "Arts, other arts/crafts", "Jewellery, fine", "Jewellery, fashion", "Watches", "Antiques, collectibles", "Pawn broking", "Scrap metal, salvage", "Real estate sale, purchase, and management", "Construction", "Real estate development", "Online learning", "Teaching and tutoring", "School, college, university", "Charity, not-for-profit", "Religious organisation", "Public sector, government", "Utilities", "Unemployed", "Retired", "In between jobs/looking for work", "Fulltime student"

  - `sourceOfFunds` (string, required)
    Source from which funds are obtained.
    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", "Loan from bank", "Inheritance", "Gift", "Other"

  - `purposeOfTransaction` (string, required)
    Purpose for the transaction.
    Enum: "investment"

  - `identityDocuments` (array, required)
    Collection of identity documents provided by the customer. (array of objects)

  - `identityDocuments.type` (string)
    The type of document provided.
    Enum: "DRIVING_LICENSE", "PASSPORT", "IDENTIFICATION", "PROOF_OF_ADDRESS", "SELFIE"

  - `identityDocuments.data` (object)
    Required when the document "type" is "PASSPORT", "DRIVING_LICENSE", or "IDENTIFICATION".

  - `identityDocuments.data.number` (string)
    Identifier number from the document.
    Example: "123456789"

  - `identityDocuments.images` (array)
    One or more images of the document.

  - `identityDocuments.images.base64` (string, required)
    Base64-encoded file content. Maximum original file size before encoding is 10 MB.
    Example: "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P49/8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="

  - `identityDocuments.images.mimetype` (string, required)
    MIME type of the image, we support image/jpeg and image/png mimetypes
    Example: "image/png"

  - `identityDocuments.images.side` (string)
    The side of the identity document
    Enum: "FRONT", "BACK"

## Response 202 fields (application/json):

  - `identityReference` (string, required)
    ASCII letters, digits, and hyphen only, A unique customer identifier provided by you. This field is required and must be unique for each customer. Please ensure you consistently reuse the same identityReference for repeat interactions with the same customer, allowing us to reliably recognize and associate their identity.
    Example: "c-13344"

  - `status` (string, required)
    Status of the onboarding request
    Enum: "PENDING", "APPROVED", "REJECTED"

  - `rejectionReason` (object)

  - `rejectionReason.internalReason` (string)
    Internal code/reason for rejection.
    Example: "Image document blurry"

  - `rejectionReason.reason` (string)
    User-facing rejection message.
    Example: "Image document blurry. Please re-submit."

  - `customerIdentity` (object)

  - `customerIdentity.givenName` (string, required)
    Customer's given / first name.
    Example: "Joe"

  - `customerIdentity.surname` (string, required)
    Customer's surname / last name.
    Example: "Bloggs"

  - `customerIdentity.dob` (string, required)
    Customer's date of birth (e.g. "1985-01-31"). Required to format as ISO 8601 Date format : YYYY-MM-DD.
    Example: "1990-01-31"

  - `customerIdentity.taxIdType` (string)
    Tax identification number (e.g. SSN). Optional unless required (e.g. for US). This is the national identifier for the customer, for example, the customer's Social Security number (SSN) in the US.  Must be a nine-digit number in the format "AAA-GG-SSSS".
    Example: "ssn"

  - `customerIdentity.taxId` (string)
    Tax identification number (e.g. SSN). Optional unless required (e.g. for US). This is the national identifier for the customer, for example, the customer's Social Security number (SSN) in the US.  Must be a nine-digit number in the format "AAA-GG-SSSS".
    Example: "123-11-123"

  - `customerIdentity.taxState` (string)
    Tax state or region if applicable.(associated with the taxId) Required format as two characters. Note; We do not accept any states where Banxa is not licensed.
    Example: "IL"

  - `customerIdentity.residentialAddress` (object, required)

  - `customerIdentity.residentialAddress.addressLine` (string, required)
    Street address.
    Example: "44 Gwynne Street"

  - `customerIdentity.residentialAddress.suburb` (string, required)
    Suburb of the address.
    Example: "Cremorne"

  - `customerIdentity.residentialAddress.state` (string, required)
    State or region, required when country is US.
    Example: "VIC"

  - `customerIdentity.residentialAddress.postCode` (string, required)
    Postal code.
    Example: "3121"

  - `customerIdentity.residentialAddress.country` (string, required)
    Country code.
    Example: "AU"

  - `occupationIndustry` (string)
    Industry related to the customer's occupation.
    Example: "Consulting, IT, or business services"

  - `occupation` (string)
    Customer's occupation.
    Example: "IT developer"

  - `purposeOfTransaction` (string)
    Purpose for the transaction.
    Example: "investment"

  - `createdAt` (string)
    The UTC date time of the identity.
    Example: "2023-06-05T19:53:08.320Z"

## Response 400 fields (application/json):

  - `message` (string)
    Example: "Bad Request"

  - `status` (integer)
    Example: 400

  - `traceId` (string)
    Idempotency key for the error
    Example: "2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f"

## Response 401 fields (application/json):

  - `message` (string)
    Example: "Unauthenticated."

  - `status` (integer)
    Example: 401

## Response 404 fields (application/json):

  - `message` (string)
    Example: "Not Found"

  - `status` (integer)
    Example: 404

## Response 422 fields (application/json):

  - `message` (string)
    Example: "The given data was invalid."

  - `errors` (object)

  - `status` (integer)
    Example: 422

## Response 429 fields (application/json):

  - `message` (string)
    Example: "Too Many Requests. Please try again later."

  - `status` (integer)
    Example: 429