--- title: "Get customer" method: GET path: "/platform/v1/customers/{customerReference}" tags: ["Customers"] --- # Get customer `GET /platform/v1/customers/{customerReference}` ## Request - Base URL: `https://api.sandbox.bvnk.com` - URL: `https://api.sandbox.bvnk.com/platform/v1/customers/{customerReference}` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) :::info Customers API v2 The [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations. If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward. ::: ## Path parameters - `customerReference` string, uuid, required ## Response `200` Success - union - GetCustomerResponseCompany - `reference` string, uuid, required: Unique customer identifier - `status` 'PENDING' | 'VERIFIED' | 'REJECTED', required: Customer external status - `type` 'COMPANY', required: Type of customer - `company` object, required: Company details - `name` string: Customer name - `description` string: Customer description - `taxResidenceCountryCode` string: Tax residency of legal person (ISO 3166-1 alpha-2). If the create request omitted it, BVNK derived it from `taxResidences`. - `registrationNumber` string: Registration number of legal person - `industry` object: Industry information - `reference` string, uuid - `name` string - `children` object[]: Sub-industries (if any) - `monthlyExpectedVolumes` object: Expected monthly volume range - `reference` string, uuid - `name` string - `min` number - `max` number - `address` object: Company address - `addressLine1` string - `addressLine2` string - `postalCode` string - `city` string - `countryCode` string - `country` string - `stateCode` string - `representative` object: Company representative details - `firstName` string - `lastName` string - `dateOfBirth` string, date - `birthCountryCode` string - `nationality` string - `address` object: Representative address - `addressLine1` string - `addressLine2` string - `postalCode` string - `city` string - `countryCode` string - `country` string - `stateCode` string - `taxResidences` TaxResidence[]: Every country where the company is resident for tax purposes. Returned only if tax data is stored for the customer. - `country` string, required: 2-letter code of the country of tax residence, in the ISO 3166-1 alpha-2 format. Must be a country supported by BVNK. - `tin` string: Tax identification number (TIN) issued by this country. Send either `tin` or `noTinReason`, not both. Placeholder values are rejected, for example `NONE`, `UNKNOWN`, `N/A`, all zeros such as `0000`, repeated characters, sequential digits such as `1234`, and values shorter than 4 characters. - `noTinReason` 'NOT_ISSUED' | 'UNABLE_TO_OBTAIN' | 'NOT_REQUIRED': Why there is no TIN for this country. Send either `tin` or `noTinReason`, not both. - `NOT_ISSUED`: The country does not issue TINs - `UNABLE_TO_OBTAIN`: The holder cannot obtain a TIN. `noTinExplanation` is required - `NOT_REQUIRED`: The country's domestic law does not require a TIN - `noTinExplanation` string: Why the holder cannot obtain a TIN. Required when `noTinReason` is `UNABLE_TO_OBTAIN`. - `countryOfIncorporation` string: Country where the company was incorporated or organised (ISO 3166-1 alpha-2). Returned only if tax data is stored for the customer. - `crsClassification` 'ACTIVE_NFE' | 'PASSIVE_NFE' | 'FI_OTHER' | 'PMIE_PARTICIPATING' | 'PMIE_NON_PARTICIPATING': Classification of the company under the OECD Common Reporting Standard (CRS). Returned only if tax data is stored for the customer. - `carfClassification` 'EXCLUDED_FI' | 'EXCLUDED_GOVERNMENT' | 'EXCLUDED_LISTED_PMIE' | 'EXCLUDED_LISTED' | 'ACTIVE_ENTITY' | 'OTHER_ENTITY': Classification of the company under the OECD Crypto-Asset Reporting Framework (CARF). Returned only if tax data is stored for the customer. - `associates` object[]: Associates of the company. A person with several titles appears once for each title. - `person` object: Personal details of the associate - `reference` string, uuid: Unique identifier for the associate person - `firstName` string: First name of the associate - `lastName` string: Last name of the associate - `dateOfBirth` string, date: Date of birth in the format YYYY-MM-DD - `placeOfBirth` string: Place of birth, for example the city - `address` AddressV2 - `addressLine1` string, required: Main address - `addressLine2` string: Apartment numbers or suite number - `postalCode` string, required: Postal code - `city` string, required: City - `countryCode` string, required: 2-letter country code in the ISO 3166-1 alpha-2 format. - `country` string: Country of residence - `stateCode` string: 2-letter state code. **Required for US customers**. - `details` object: Additional identification and contact details for the associate - `nationality` string: ISO 3166-1 alpha-2 country code of nationality - `contactInfo` object: Contact details for the associate - `emailAddress` string: Primary email address - `phoneNumber` string: Phone number in international format - `documentNumber` string: Primary identification document number - `documentInfo` object: Information about identification document - `number` string: Identification document number - `type` 'PASSPORT' | 'ID_CARD' | 'DRIVERS' | 'RESIDENCE_PERMIT' | 'OTHER': Identity document type: - `PASSPORT`: Passport - `ID_CARD`: National ID card - `DRIVERS`: Driver's licence - `RESIDENCE_PERMIT`: Residence permit - `OTHER`: Other government-issued ID - `issuingCountryCode` string: Country code of the issuing authority (ISO 3166-1 alpha-2) - `taxIdentification` object: Tax identification information. If the create request omitted it, BVNK derived it from the associate's `taxResidences`. - `number` string: Tax identification number - `taxResidenceCountryCode` string: Country of tax residency (ISO 3166-1 alpha-2) - `title` 'BUSINESS_OWNER' | 'ACCOUNT_REPRESENTATIVE' | 'DIRECTOR': Title of the associate in this entry - `controls` object: Control details for the associate - `hasOwnership` boolean: Whether the associate owns part of the company - `hasControl` boolean: Whether the associate controls the company - `isSigner` boolean: Whether the associate can sign on behalf of the company - `ownership` object: Ownership details for the associate - `type` 'DIRECT' | 'INDIRECT': Ownership type. - DIRECT: The associate has a direct, immediate ownership stake or relationship with the company. - INDIRECT: The associate's ownership or control flows through one or more intermediary entities. - `percentage` number: Ownership percentage - `controllingPersonRole` 'LP_OWNERSHIP' | 'LP_OTHER_MEANS' | 'LP_SENIOR_MANAGING_OFFICIAL' | 'TRUST_SETTLOR' | 'TRUST_TRUSTEE' | 'TRUST_PROTECTOR' | 'TRUST_BENEFICIARY' | 'TRUST_OTHER' | 'ARR_SETTLOR_EQ' | 'ARR_TRUSTEE_EQ' | 'ARR_PROTECTOR_EQ' | 'ARR_BENEFICIARY_EQ' | 'ARR_OTHER_EQ': Type of controlling person under the OECD CRS and CARF. Returned only if tax data is stored for the associate. - `LP_OWNERSHIP`: Legal person, control by ownership - `LP_OTHER_MEANS`: Legal person, control by other means - `LP_SENIOR_MANAGING_OFFICIAL`: Legal person, senior managing official - `TRUST_SETTLOR`: Trust, settlor - `TRUST_TRUSTEE`: Trust, trustee - `TRUST_PROTECTOR`: Trust, protector - `TRUST_BENEFICIARY`: Trust, beneficiary - `TRUST_OTHER`: Trust, other - `ARR_SETTLOR_EQ`: Legal arrangement other than a trust, settlor-equivalent - `ARR_TRUSTEE_EQ`: Legal arrangement other than a trust, trustee-equivalent - `ARR_PROTECTOR_EQ`: Legal arrangement other than a trust, protector-equivalent - `ARR_BENEFICIARY_EQ`: Legal arrangement other than a trust, beneficiary-equivalent - `ARR_OTHER_EQ`: Legal arrangement other than a trust, other-equivalent - `taxResidences` TaxResidence[]: Every country where the associate is resident for tax purposes. Returned only if tax data is stored for the associate. - `country` string, required: 2-letter code of the country of tax residence, in the ISO 3166-1 alpha-2 format. Must be a country supported by BVNK. - `tin` string: Tax identification number (TIN) issued by this country. Send either `tin` or `noTinReason`, not both. Placeholder values are rejected, for example `NONE`, `UNKNOWN`, `N/A`, all zeros such as `0000`, repeated characters, sequential digits such as `1234`, and values shorter than 4 characters. - `noTinReason` 'NOT_ISSUED' | 'UNABLE_TO_OBTAIN' | 'NOT_REQUIRED': Why there is no TIN for this country. Send either `tin` or `noTinReason`, not both. - `NOT_ISSUED`: The country does not issue TINs - `UNABLE_TO_OBTAIN`: The holder cannot obtain a TIN. `noTinExplanation` is required - `NOT_REQUIRED`: The country's domestic law does not require a TIN - `noTinExplanation` string: Why the holder cannot obtain a TIN. Required when `noTinReason` is `UNABLE_TO_OBTAIN`. - GetCustomerResponseIndividual - `reference` string, uuid, required: Unique customer identifier - `status` 'PENDING' | 'VERIFIED' | 'REJECTED', required: Customer internal status - `type` 'INDIVIDUAL', required: Type of customer - `individual` object, required: Individual details - `description` string: Customer description - `person` object: Personal identification details of the individual - `reference` string, uuid: Unique identifier for the individual - `firstName` string: First name of the individual - `lastName` string: Last name of the individual - `dateOfBirth` string, date: Date of birth in the format YYYY-MM-DD - `placeOfBirth` string: ISO 3166-1 alpha-2 country code of birth - `address` AddressV2 - `addressLine1` string, required: Main address - `addressLine2` string: Apartment numbers or suite number - `postalCode` string, required: Postal code - `city` string, required: City - `countryCode` string, required: 2-letter country code in the ISO 3166-1 alpha-2 format. - `country` string: Country of residence - `stateCode` string: 2-letter state code. **Required for US customers**. - `taxResidences` TaxResidence[]: Every country where the individual is resident for tax purposes. Returned only if tax data is stored for the customer. - `country` string, required: 2-letter code of the country of tax residence, in the ISO 3166-1 alpha-2 format. Must be a country supported by BVNK. - `tin` string: Tax identification number (TIN) issued by this country. Send either `tin` or `noTinReason`, not both. Placeholder values are rejected, for example `NONE`, `UNKNOWN`, `N/A`, all zeros such as `0000`, repeated characters, sequential digits such as `1234`, and values shorter than 4 characters. - `noTinReason` 'NOT_ISSUED' | 'UNABLE_TO_OBTAIN' | 'NOT_REQUIRED': Why there is no TIN for this country. Send either `tin` or `noTinReason`, not both. - `NOT_ISSUED`: The country does not issue TINs - `UNABLE_TO_OBTAIN`: The holder cannot obtain a TIN. `noTinExplanation` is required - `NOT_REQUIRED`: The country's domestic law does not require a TIN - `noTinExplanation` string: Why the holder cannot obtain a TIN. Required when `noTinReason` is `UNABLE_TO_OBTAIN`. - `details` object: Additional identification and contact details for the individual - `nationality` string: ISO 3166-1 alpha-2 country code of nationality - `birthCountryCode` string: ISO 3166-1 alpha-2 code of birth country - `contactInfo` object: Contact details for the individual - `emailAddress` string: Primary email address - `phoneNumber` string: Phone number in international format - `documentNumber` string: Primary identification document number - `documentInfo` object: Information about identification document - `number` string: Identification document number - `type` 'PASSPORT' | 'ID_CARD' | 'DRIVERS' | 'RESIDENCE_PERMIT' | 'OTHER': Identity document type: - `PASSPORT`: Passport - `ID_CARD`: National ID card - `DRIVERS`: Driver's licence - `RESIDENCE_PERMIT`: Residence permit - `OTHER`: Other government-issued ID - `issuingCountryCode` string: Country code of the issuing authority (ISO 3166-1 alpha-2) - `taxIdentification` object: Tax identification information. If the create request omitted it, BVNK derived it from `person.taxResidences`. - `number` string: Tax identification number - `taxResidenceCountryCode` string: Country of tax residency (ISO 3166-1 alpha-2) - `cdd` object: Customer due diligence details - `intendedUseOfAccount` 'TRANSFERS_OWN_WALLET' | 'TRANSFERS_FAMILY_FRIENDS' | 'INVESTMENTS' | 'GOODS_SERVICES' | 'DONATIONS': Purpose of the account: - `TRANSFERS_OWN_WALLET`: Transfers to or from own wallet including bank accounts - `TRANSFERS_FAMILY_FRIENDS`: Transfers to or from family and friends - `INVESTMENTS`: Investments - `GOODS_SERVICES`: Purchases of goods and services - `DONATIONS`: Donations - `pepStatus` 'NOT_PEP' | 'FORMER_PEP_2_YEARS' | 'FORMER_PEP_OLDER' | 'DOMESTIC_PEP' | 'FOREIGN_PEP' | 'CLOSE_ASSOCIATES' | 'FAMILY_MEMBERS': Politically Exposed Person status: - `NOT_PEP`: Not a PEP - `FORMER_PEP_2_YEARS`: Former or inactive PEP (within 2 years) - `FORMER_PEP_OLDER`: Former or inactive PEP (older than 2 years) - `DOMESTIC_PEP`: Domestic PEP - `FOREIGN_PEP`: Foreign PEP - `CLOSE_ASSOCIATES`: Close associates - `FAMILY_MEMBERS`: Family members - `expectedMonthlyVolume` object: Expected monthly transaction volume - `amount` number: Monthly transaction volume amount - `currency` string: Currency of the transaction volume (ISO 4217 code) - `employmentStatus` 'SELF_EMPLOYED' | 'SALARIED' | 'UNEMPLOYED' | 'RETIRED' | 'STUDENT': Employment status: - `SELF_EMPLOYED`: Self employed and freelancer - `SALARIED`: Salaried - `UNEMPLOYED`: Unemployed - `RETIRED`: Retired - `STUDENT`: Student - `sourceOfFunds` 'SALARY' | 'PENSION' | 'SAVINGS' | 'SELF_EMPLOYMENT' | 'CRYPTO_TRADING' | 'GAMBLING' | 'REAL_ESTATE' | 'GIFT' | 'STUDENT_LOAN': Source of funds: - `SALARY`: Salary and employment income - `PENSION`: Pension and retirement income - `SAVINGS`: Savings and investments - `SELF_EMPLOYMENT`: Self employment and business income - `CRYPTO_TRADING`: Crypto trading - `GAMBLING`: Gambling and lottery winnings - `REAL_ESTATE`: Real estate sales - `GIFT`: Gifts - `STUDENT_LOAN`: Student Loan - `estimatedYearlyIncome` 'INCOME_0_TO_50K' | 'INCOME_50K_TO_100K' | 'INCOME_100K_TO_250K' | 'INCOME_250K_TO_500K' | 'INCOME_500K_TO_750K' | 'INCOME_750K_TO_1M' | 'INCOME_ABOVE_1M': Estimated yearly income range. **Mandatory for US residents under the Partner-managed model**. - `INCOME_0_TO_50K`: 0 to 50,000 USD - `INCOME_50K_TO_100K`: 50,000 to 100,000 USD - `INCOME_100K_TO_250K`: 100,000 to 250,000 USD - `INCOME_250K_TO_500K`: 250,000 to 500,000 USD - `INCOME_500K_TO_750K`: 500,000 to 750,000 USD - `INCOME_750K_TO_1M`: 750,000 to 1,000,000 USD - `INCOME_ABOVE_1M`: Above 1,000,000 USD - `employmentIndustrySector` 'INVESTMENT' | 'HEDGE_FUND' | 'MONEY_SERVICE_BUSINESS' | 'STO_ISSUER' | 'PRECIOUS_METALS' | 'NON_PROFIT' | 'REGISTERED_INVESTMENT_ADVISOR' | 'AGRICULTURE_FORESTRY_FISHING_HUNTING' | 'MINING' | 'UTILITIES' | 'CONSTRUCTION' | 'MANUFACTURING' | 'WHOLESALE_TRADE' | 'RETAIL_TRADE' | 'TRANSPORTATION_WAREHOUSING' | 'INFORMATION' | 'FINANCE_INSURANCE' | 'REAL_ESTATE_RENTAL_LEASING' | 'PROFESSIONAL_SCIENTIFIC_TECHNICAL_SERVICES' | 'MANAGEMENT_OF_COMPANIES_ENTERPRISES' | 'ADMINISTRATIVE_SUPPORT_WASTE_MANAGEMENT_REMEDIATION_SERVICES' | 'EDUCATIONAL_SERVICES' | 'HEALTH_CARE_SOCIAL_ASSISTANCE' | 'ARTS_ENTERTAINMENT_RECREATION' | 'ACCOMMODATION_FOOD_SERVICES' | 'OTHER_SERVICES' | 'PUBLIC_ADMINISTRATION' | 'NOT_CLASSIFIED' | 'ADULT_ENTERTAINMENT' | 'AUCTIONS' | 'AUTOMOBILES' | 'BLOCKCHAIN' | 'CRYPTO' | 'DRUGS' | 'EXPORT_IMPORT' | 'E_COMMERCE' | 'FINANCIAL_INSTITUTION' | 'GAMBLING' | 'INSURANCE' | 'MARKET_MAKER' | 'SHELL_BANK' | 'TRAVEL_TRANSPORT' | 'WEAPONS': Employment industry sector. **Required if your customers are individuals domiciled in a US state**. - `flowType` string: Flow type used for customer creation - `riskScore` 'LOW' | 'MEDIUM' | 'HIGH': Risk score of the customer - `verification` object: Verification status - `status` string ## Other responses - `400`: Bad Request - `404`: The specified resource was not found ## Changes - **2026-11-06** `c386d436bf2c`: 3 warning, 7 info - added the new `GIFT` enum value to the `oneOf[#/components/schemas/GetCustomerResponseIndividual]/individual/cdd/sourceOfFunds` response property for the response status `200` - added the new `STUDENT` enum value to the `oneOf[#/components/schemas/GetCustomerResponseIndividual]/individual/cdd/employmentStatus` response property for the response status `200` - added the new `STUDENT_LOAN` enum value to the `oneOf[#/components/schemas/GetCustomerResponseIndividual]/individual/cdd/sourceOfFunds` response property for the response status `200` - added the optional property `oneOf[#/components/schemas/GetCustomerResponseCompany]/company/associates` to the response with the `200` status - …6 more - …earlier changes not shown [Operation history](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/changes/platform/v1/customers/:customerReference/get.md) --- [API](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints.md) - [All operations](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/llms.txt) - [OpenAPI document](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/revisions/c386d436bf2c?raw)