A customer represents a single end-user. Almost every action in Helix requires a customerId to identify for whom the action is being performed. To correlate a customer in Helix to a user in your system, you can:

  1. Pass your system's unique user ID into the tag property during customer creation. This allows you to use your system's ID to fetch the customer's Helix data via /customer/getByTag
  2. Capture and store the unique customerId returned by Helix after customer creation. You can then use /customer/Get to fetch the customer's Helix data.


customer Object

PropertyData Type (length)Description
accessTypeCodedeprecateddeprecated
accountsarrayAn array of account objects owned by the customer
addressesarrayAn array of address objects associated with the customer
attestationDate*datetimeDate the business information was attested to
attesterName*string (50)Name of the person attesting to the business' information
attesterTitle*string (50)Title of the person attesting to the business' information
birthDatedatetimeCustomer birth date
Format: yyyy-MM-ddT00:00:00.000+00:00
Example: 1976-07-04T00:00:00.000+00:00
businessDescription*string (200)Description of the business
businessLegalName*string (300)Legal name of the business
businessNameOnCard*string (30)Optional. The business name printed on the card
businessWebsite*string (100)Url of the business
cardsarrayAn array of card objects owned by the customer
createdDatedatetimeDate the customer was created. Note: a customer may have been created but is not available for use, depending on the isLocked or status properties.
cultureenumAccepted values vary by program. Possible values:
- en-US: English
- es-US: Spanish
customerIdintegerThe Helix-assigned unique ID for a customer. Will be
returned via /customer/create . Used as a parameter to
almost every other Helix route
customField1string (50)A property for holding client-defined data. There is no
business logic in Helix for a custom field
customField2string (50)A property for holding client-defined data. There is no
business logic in Helix for a custom field
customField3string (50)A property for holding client-defined data. There is no
business logic in Helix for a custom field
customField4string (50)A property for holding client-defined data. There is no
business logic in Helix for a custom field
customField5string (50)A property for holding client-defined data. There is no
business logic in Helix for a custom field
doingBusinessAs*string (200)"DBA" or "Fictitious Business Name" of the business
deceasedDatedatetimeDenotes the date the customer was reported as deceased.
Example: 2014-01-01T00:00:00.000+00:00
driversLicenseExpireDatedatetimeDate the driver's license expires.
Format: yyyy-MM-ddT00:00:00.000+00:00
Example: 2024-07-04T00:00:00.000+00:00
driversLicenseIssueDatedatetimeDate the driver's license was issued.
Format: yyyy-MM-ddT00:00:00.000+00:00
Example: 2020-07-04T00:00:00.000+00:00
driversLicenseNumberstring (30)The identifying number from a government-issued driver's license
driversLicenseNumberMaskedstringLast 4 digits of the driversLicenseNumber property value,
preceded by 6 '*'.
Example: ******1234
driversLicenseStatestring (2)State from which the driver's license is issued.
Example: CA
emailAddressstring (255)Customer email address
Example: [email protected]
exemptFromBeneficialOwnershipReasonType*enumThe reason the business is exempt from Beneficial Ownership. See customer.exemptFromBeneficialOwnershipType for more details.
Possible values:
- UsStockExchangeTradedEntity
- CharityOrNonProfitEntity
- PublicAccountingFirmRegisteredUnderSection102
- UsStateRegulatedBank
- UsRegulatedInsuranceCompany
- UsRegulatedFinancialInstitution
- UsFederalGovernmentAgency
- UsStateGovernmentAgency
- UsLocalGovernmentAgency
- NonUsGovernmentAgency
- BankHoldingCompany
- SavingsAndLoanHoldingCompany
- FinancialMarketUtility
- NonUsEntityOpeningAPrivateBankingAccount
- ForeignFinancialInstitution
- ClassOfSecuritiesIssuer
- SecCurrentRegisteredFirm
- CommodityFuturesTradingCommissionRegisteredEntity
- ExcludedPooledInvestmentVehicle
- NonExludedPooledInvestmentVehicle
- UsStockExchangeMajorityEquityEntity
externalAccountsarrayAn array of externalAccount objects owned by the customer
firstNamestring (64)First (given) name
foreignDocumentCountryCodestring (3)3 character country code of the country the document was issued by. See ISO 3166-1 Country Codes
foreignDocumentExpirationDatedatetimeExpiration date of the foreign ID
foreignDocumentNumberstring (30)Unique number of the foreign ID
foreignDocumentTypeenumValid values:
- DriversLicense
- ConsularIdCard
- Passport
- PermanentResidentCard
- EmploymentAuthorizationCard
- VoterRegistrationCard
- IdentificationCard
formationDate*datetimeDate the business was originally registered
formationState*string (2)2-character state abbreviation of the state where the business was registered
fraudStatusenumCustomer's status in regards to the 'fraud' customer verification module. Possible Values:
- Verified
- Denied
- Automated Review
- Manual Review
- Null/Blank
genderenumCustomer gender
Valid values include:
- M: Male
- F: Female
- U: Unknown/Unspecified
industryClassificationCodeId*integerHelix-assigned unique ID for the industry in which a business operates

See the industryClassificationCode object for more information.
isActivedeprecatedUse status instead
isBusinessbooleanIndicates whether the customer is a natural person or business entity.
isDocumentsAcceptedbooleanOnly required when creating a new customer. Confirms that customer viewed and accepted all documents returned via the /bankDocument/list route
isExemptFromBeneficialOwnership*booleanIndicates if the business is exempt from providing beneficial ownership information
isLockedbooleanDenotes if a customer is locked, typically caused by fraud prevention mechanisms or manual intervention via the admin console. A locked customer can not transfer any funds
isMinorbooleantrue if the customer is an individual and under 18 years of age
isOptedInToBankCommunicationbooleanIndicates whether the customer opted in to receiving marketing notifications from the bank. Note: customer may possibly still receive other required notifications from the bank regardless of this flag -- it depends on your program and the bank.
isSubjectToBackupWithholdingbooleanIndicates whether the customer is subject to backup withholding. Helix will withhold the appropriate
percentage of earned interest and submit these funds
directly to the IRS. The amount withheld will be reported on the annual 1099-INT generated by Helix. Refer to the Backup Withholding topic at the IRS website for additional details.
isTaxExempt*booleanIndicates if the customer exempt from US taxes
kybStatus*enumPossible values:
- Initiated
- Manual Review
- Verified
- Denied
- Expired
- Deceased
- Archived
- Automated Review
kybStatusDate*datetimeThe last time kybStatus was modified
kycStatusenumCustomer's status in regards to the 'KYC' customer verification module. Possible Values:
- Verified
- Denied
- Automated Review
- Manual Review
- Null/Blank
lastActivityDatedatetimeTimestamp for the last time any action was performed on this customer. Actions include listing, editing, archiving,
closing, transferring funds, or otherwise "touching" any
data specific to this customer, whether it is via the API, a
Bulk Transfer Request file, or the Admin console
lastContactDatedatetimeDate of last contact with the customer. Set via /customer/setLastContact
lastContactTypeenumType of last contact with the customer. Set via /customer/setLastContact. Date of last contact with the customer. Set via /customer/setLastContact.
Valid values:
- Log In
- Phone
- Email
- Chat
- Other
lastModifiedDatedatetimeDate when the object was last altered in any way
lastNamestring (128)Last name (surname)
legalEntityTypeenumPossible values:
- Individual
- SingleMemberLLC
- SCorporation
- CCorporation
- SoleProprietorship
- NonProfit
- Association
- Partnership
- LimitedLiabilityCompany
- LimitedLiabilityPartnership
- RevocableTrust
- IrrevocableTrust
- FinancialInstitutionOther
- Estate
- Trust
- Church
- Conservator
- Guardianship
- Government
- Cooperative
- BCorporation
- TottenTrustPOD
- LimitedPartnership
- GeneralPartnership
- GovernmentDepartment
- GovernmentAgency
- GovernmentAuthority
- GovernmentNonCommercialNonUSDepartmentOrAgency
- GovernmentOther
- RegulatedFinancialInstitution
- RegulatedBankLoanHoldingsCompany
- RegulatedSavingsAndLoanHoldingCompany
- ForeignFinancialInstitutionRegulatorKeepsUBOInfo
lockedDatedatetimeDenotes the last time isLocked was set to true. Note: if isLocked is changed to false, this value will not reset.
Example: 2014-01-01T00:00:00.000+00:00
lockedReasonstringThe reason isLocked was set to true. Freeform. Note: if isLocked is changed to false, this value will not reset.
middleNamestring (64)Middle name
ofacStatusenumCustomer's status in regards to the 'ofac' customer verification module. Possible Values:
- Verified
- Manual Review
- Null/Blank
passportCountrystring (5)Country from which the passport is issued.
Example: US
passportExpireDatedatetimeDate the passport expires
Format: yyyy-MM-ddT00:00:00.000+00:00
Example: 2030-07-04T00:00:00.000+00:00
passportIssueDatedatetimeDate the passport was issued.
Format: yyyy-MM-ddT00:00:00.000+00:00
Example: 2020-07-04T00:00:00.000+00:00
passportNumberstring (30)Identifying number from a government-issued passport
passportNumberMaskedstringLast 4 digits of the passportNumberMasked property, preceded by 6 '*'.
Example: ******1234
phonesarrayAn array of phone objects associated with the customer
preferredName**string (21)Optional. Name a customer prefers to use and referred to when being addressed.
residencyStatusTypeenumPossible values:
- USCitizen
- ResidentAlien
- NonResidentAlien
statusenumPossible values:
- Active*
- Denied
- Expired
- Archived
- Deceased
- Initiated**
- Manual Review**
- Verified* **

*Values are effectively the same. Helix database, reporting, and bulk files will reflect Verified. For programs not using legacy onboarding API endpoints, Helix Admin Console and API reflect as Active.

**Only valid for programs using legacy onboarding API endpoints. Programs using Helix's /customer/onboard API endpoint will not see these values.
suffixstring (20)A customer's name suffix. Examples:
- Sr.
- Esq.
- Ph.D
tagstring (50)A client-assigned, unique identifier to represent exactly one customer in the Helix production environment. This typically represents the user ID in your system. The Helix sandbox environment allows duplicate tags for testing.
taxIdstring (30)Social Security Number (SSN), Employer Identification Number (EIN) or Individual Taxpayer Identification Number (ITIN)

Numeric characters only, no formatting (i.e., hyphens, spaces) of any kind

Example: 123456789
taxIdMaskedstringLast 4 digits of the taxId property, preceded by 6 '*'.
Example: ******1234
taxIdTypeenumPossible values:
- SSN: Social Security Number
- EIN: Employer Identification Number
- ITIN: Individual Taxpayer Identification Number

Note: A null value will be interpreted as SSN
usePreferredNameOnCard**booleanDefault is false. Specifies the customer's preference to have preferredName printed on their physical card instead of the nameOnCard.  When set to true the card will be printed with `preferredName on file and card mailer and Visa DPS will reflect nameOnCard.

*Property relates to business account functionality. Use of business account functionality requires approval from Q2 and your bank partner.

**Property relates to Preferred Name functionality. Use of Preferred Name functionality requires approval from Q2 and your bank partner.