Customer

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

Property

Data Type (length)

Description

accessTypeCodedeprecateddeprecated

accounts

array

An array of account objects owned by the customer

addresses

array

An array of address objects associated with the customer

attestationDate*

datetime

Date 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

birthDate

datetime

Customer 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 (26)

Optional. The business name printed on the card. See card name allowed special characters for more details

businessWebsite*

string (100)

Url of the business

cards

array

An array of card objects owned by the customer

createdDate

datetime

Date the customer was created. Note: a customer may have been created but is not available for use, depending on theisLocked or status properties.

culture

enum

Accepted values vary by program. Possible values:

  • en-US: English
  • es-US: Spanish

customerId

integer

The Helix-assigned unique ID for a customer. Will be
returned via /customer/create . Used as a parameter to
almost every other Helix route

customField1

string (50)

A property for holding client-defined data. There is no
business logic in Helix for a custom field

customField2

string (50)

A property for holding client-defined data. There is no
business logic in Helix for a custom field

customField3

string (50)

A property for holding client-defined data. There is no
business logic in Helix for a custom field

customField4

string (50)

A property for holding client-defined data. There is no
business logic in Helix for a custom field

customField5

string (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

deceasedDate

datetime

Denotes the date the customer was reported as deceased.
Example: 2014-01-01T00:00:00.000+00:00

driversLicenseExpireDate

datetime

Date the driver's license expires.
Format: yyyy-MM-ddT00:00:00.000+00:00
Example: 2024-07-04T00:00:00.000+00:00

driversLicenseIssueDate

datetime

Date the driver's license was issued.
Format: yyyy-MM-ddT00:00:00.000+00:00
Example: 2020-07-04T00:00:00.000+00:00

driversLicenseNumber

string (30)

The identifying number from a government-issued driver's license

driversLicenseNumberMasked

string

Last 4 digits of the driversLicenseNumber property value,
preceded by 6 '*'.
Example: ******1234

driversLicenseState

string (2)

State from which the driver's license is issued.
Example: CA

emailAddress

string (255)

Customer email address
Example: [email protected]

exemptFromBeneficialOwnershipReasonType*

enum

The 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

externalAccounts

array

An array of externalAccount objects owned by the customer

firstName

string (64)

First (given) name

foreignDocumentCountryCode

string (3)

3 character country code of the country the document was issued by. See ISO 3166-1 Country Codes

foreignDocumentExpirationDate

datetime

Expiration date of the foreign ID

foreignDocumentNumber

string (30)

Unique number of the foreign ID

foreignDocumentNumberMasked

string

Masked value of foreignDocumentNumber

foreignDocumentType

enum

Valid values:

  • DriversLicense
  • ConsularIdCard
  • Passport
  • PermanentResidentCard
  • EmploymentAuthorizationCard
  • VoterRegistrationCard
  • IdentificationCard

formationDate*

datetime

Date the business was originally registered

formationState*

string (2)

2-character state abbreviation of the state where the business was registered

fraudStatus

enum

Customer's status in regards to the 'fraud' customer verification module. Possible Values:

  • Verified
  • Denied
  • Automated Review
  • Manual Review
  • Null/Blank

gender

enum

Customer gender
Valid values include:

  • M: Male
  • F: Female
  • U: Unknown/Unspecified

industryClassificationCodeId*

integer

Helix-assigned unique ID for the industry in which a business operates

See the industryClassificationCode object for more information.

isActivedeprecatedUse status instead

isBusiness

boolean

Indicates whether the customer is a natural person or business entity.

isDocumentsAccepted

boolean

Only required when creating a new customer. Confirms that customer viewed and accepted all documents returned via the /bankDocument/list route

isExemptFromBeneficialOwnership*

boolean

Indicates if the business is exempt from providing beneficial ownership information

isLocked

boolean

Denotes 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

isMinor

boolean

true if the customer is an individual and under 18 years of age

isOptedInToBankCommunication

boolean

Indicates 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.

isSubjectToBackupWithholding

boolean

Indicates 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*

boolean

Indicates if the customer exempt from US taxes

kybStatus*

enum

Possible values:

  • Initiated
  • Manual Review
  • Verified
  • Denied
  • Expired
  • Deceased
  • Archived
  • Automated Review

kybStatusDate*

datetime

The last time kybStatus was modified

kycStatus

enum

Customer's status in regards to the 'KYC' customer verification module. Possible Values:

  • Verified
  • Denied
  • Automated Review
  • Manual Review
  • Null/Blank

lastActivityDate

datetime

Timestamp 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

lastContactDate

datetime

Date of last contact with the customer. Set via /customer/setLastContact

lastContactType

enum

Type 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

lastModifiedDate

datetime

Date when the object was last altered in any way

lastName

string (128)

Last name (surname)

legalEntityType

enum

Possible 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

lockedDate

datetime

Denotes the last time isLocked was set to true. Note: ifisLocked is changed to false, this value will not reset.
Example: 2014-01-01T00:00:00.000+00:00

lockedReason

string

The reason isLocked was set to true. Freeform. Note: ifisLocked is changed to false, this value will not reset.

middleName

string (64)

Middle name

ofacStatus

enum

Customer's status in regards to the 'ofac' customer verification module. Possible Values:

  • Verified
  • Manual Review
  • Null/Blank

passportCountry

string (5)

Country from which the passport is issued.
Example: US

passportExpireDate

datetime

Date the passport expires
Format: yyyy-MM-ddT00:00:00.000+00:00
Example: 2030-07-04T00:00:00.000+00:00

passportIssueDate

datetime

Date the passport was issued.
Format: yyyy-MM-ddT00:00:00.000+00:00
Example: 2020-07-04T00:00:00.000+00:00

passportNumber

string (30)

Identifying number from a government-issued passport

passportNumberMasked

string

Last 4 digits of the passportNumberMasked property, preceded by 6 '*'.
Example: ******1234

phones

array

An array of phone objects associated with the customer

preferredName**

string (21)

Optional. Name a customer prefers to use and referred to when being addressed.

residencyStatusType

enum

Possible values:

  • USCitizen
  • ResidentAlien
  • NonResidentAlien

status

enum

Possible values:

  • Active*
  • Denied
  • Expired
  • Archived
  • Deceased
  • Initiated**
  • Manual Review**
  • Verified* **

*Values are effectively the same. Helix database, reporting, and bulk files will reflectVerified. 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.

suffix

string (20)

A customer's name suffix. Examples:

  • Sr.
  • Esq.
  • Ph.D

tag

string (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.

taxId

string (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

taxIdMasked

string

Last 4 digits of the taxId property, preceded by 6 '*'.
Example: ******1234

taxIdType

enum

Possible values:

  • SSN: Social Security Number
  • EIN: Employer Identification Number
  • ITIN: Individual Taxpayer Identification Number
  • *Note:** A null value will be interpreted as SSN

usePreferredNameOnCard**

boolean

Default 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.