Receive account holder information

Receive Account Holder Information

The GET /v2/holder endpoint retrieves comprehensive profile information for the currently authenticated account holder. It returns both personal and business identity data, application status, security settings, and profile configuration in a single response. Only authenticated users with a valid Bearer token can access this sensitive account information.

Endpoint

GET /v2/holder

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint to retrieve the full account holder profile after authentication, such as when populating a dashboard with the holder's personal or business details. It is also useful for checking the application status, banking approval state, MFA/OTP security settings, and profile-level transfer and financial account limits. Both personal and business account holders are supported; the relevant object (accountHolderInformation or businessAccountHolder) will be populated based on account type.

Response

200 OK

Top-level fields

Field	Type	Description
`id`	integer (int32)	Internal record identifier
`createdDate`	string (date-time)	Date and time the profile was created
`updatedDate`	string (date-time) \| null	Date and time the profile was last updated
`userProfileId`	integer (int32)	Linked user profile identifier
`step`	integer (int32)	Onboarding step indicator (0–4)
`accountHolderInformation`	object	Personal account holder details (see below)
`businessAccountHolder`	object	Business account holder details (see below)
`isSubmitted`	boolean \| null	Whether the application has been submitted
`accountHolderId`	string \| null	External account holder identifier
`nickName`	string \| null	Display nickname for the account holder
`cardProductId`	string \| null	Associated card product identifier
`openApplicationId`	string \| null	Identifier of an open banking application
`financialAccountId`	string \| null	Primary financial account identifier
`applicationStatus`	integer (int32)	Numeric application status code (0–4)
`bankingStatus`	string	String application status (e.g., `Approved`, `PendingUW`, `Denied`)
`applicationDate`	string (date-time) \| null	Date the application was submitted
`approvalDate`	string (date-time) \| null	Date the application was approved
`isDeleted`	boolean	Whether the profile has been soft-deleted
`isLocked`	boolean	Whether the account is locked
`isAccessLocked`	boolean	Whether login access is locked (e.g., after repeated failed login attempts)
`isMfaEnabled`	boolean	Whether multi-factor authentication is enabled
`isOtpEnabled`	boolean	Whether one-time password authentication is enabled
`agentPayoutProfileId`	integer (int32) \| null	Associated agent payout profile, if any
`salesRepresentativeId`	integer (int32) \| null	Associated sales representative, if any
`rewordType`	integer (int32)	Rewards type for the account (1, 2, or 4)
`isNew`	boolean \| null	Whether the account is newly created
`isExceptional`	boolean \| null	Whether the account has exceptional status
`profileSettings`	object	Profile-level settings (see below)
`applicationCreationType`	string	Channel through which the application was created (e.g., `BankingAPI`, `NeteviaAPI`)
`exceptionalTemplateId`	integer (int32) \| null	Exceptional template identifier, if applicable
`profileType`	integer (int32)	Profile type code (0–3)
`accountType`	integer (int32)	Account type code (1–5)
`employer`	object	Associated employer profile (EWA), if any
`lockFinancialAccountId`	string \| null	Financial account ID used for locking purposes
`agreements`	array \| null	List of accepted agreements (see below)

accountHolderInformation object (personal accounts)

Field	Type	Description
`id`	integer (int32)	Record identifier
`createdDate`	string (date-time)	Record creation timestamp
`updatedDate`	string (date-time) \| null	Record last-updated timestamp
`email`	string \| null	Account holder email address
`givenName`	string \| null	First name
`familyName`	string \| null	Last name
`middleName`	string \| null	Middle name
`phone`	string \| null	Primary phone number
`ssn`	string \| null	Social Security Number (masked: `XXX-XX-XXXX`)
`dateOfBirth`	string (date-time) \| null	Date of birth
`streetAddress`	string \| null	Street address (read-only)
`extendedAddress`	string \| null	Address line 2 (read-only)
`postalCode`	string \| null	ZIP/postal code (read-only)
`locality`	string \| null	City (read-only)
`state`	integer (int32)	US state code (1–53)
`countryCodeAlpha3`	string \| null	ISO 3166-1 alpha-3 country code (read-only)

businessAccountHolder object (business accounts)

Field	Type	Description
`id`	integer (int32)	Record identifier
`createdDate`	string (date-time)	Record creation timestamp
`updatedDate`	string (date-time) \| null	Record last-updated timestamp
`email`	string \| null	Primary authorized person email
`givenName`	string \| null	Primary authorized person first name
`familyName`	string \| null	Primary authorized person last name
`middleName`	string \| null	Primary authorized person middle name
`phone`	string \| null	Primary authorized person phone number
`ssn`	string \| null	Primary authorized person SSN (masked: `XXX-XX-XXXX`)
`dateOfBirth`	string (date-time) \| null	Primary authorized person date of birth
`streetAddress`	string \| null	Business street address (read-only)
`extendedAddress`	string \| null	Business address line 2 (read-only)
`postalCode`	string \| null	Business ZIP/postal code (read-only)
`locality`	string \| null	Business city (read-only)
`state`	integer (int32)	Business US state code (1–53)
`countryCodeAlpha3`	string \| null	ISO 3166-1 alpha-3 country code (read-only)
`percentageOwnership`	integer (int32)	Ownership percentage of the primary authorized person
`authorizingPersonTitle`	integer (int32)	Title of the authorizing person (0–6)
`legalBusinessName`	string \| null	Legal registered business name
`doingBusinessAsName`	string \| null	DBA name
`website`	string \| null	Business website URL
`businessType`	integer (int32)	Business entity type (0–4)
`businessPhone`	string \| null	Business phone number
`employerIdentificationNumber`	string \| null	EIN (masked in production)
`primaryAuthorizedPersonId`	string \| null	External ID of the primary authorized person
`primaryAuthorizedStreetAddress`	string \| null	Primary authorized person street address (read-only)
`primaryAuthorizedExtendedAddress`	string \| null	Primary authorized person address line 2 (read-only)
`primaryAuthorizedPostalCode`	string \| null	Primary authorized person ZIP code (read-only)
`primaryAuthorizedLocality`	string \| null	Primary authorized person city (read-only)
`primaryAuthorizedState`	integer (int32)	Primary authorized person US state code (1–53)
`businessStartDate`	string (date-time) \| null	Date the business was established
`annualBusinessRevenue`	integer (int64) \| null	Annual business revenue in cents
`payrollCustomer`	boolean \| null	Whether the business is a payroll customer
`owners`	array \| null	List of additional business owners (see owner object below)
`merchantProfileId`	integer (int32) \| null	Associated merchant profile identifier

owners array item object

Field	Type	Description
`id`	integer (int32)	Record identifier
`createdDate`	string (date-time)	Record creation timestamp
`updatedDate`	string (date-time) \| null	Record last-updated timestamp
`businessAccountId`	integer (int32)	Parent business account identifier
`givenName`	string \| null	Owner first name
`familyName`	string \| null	Owner last name
`middleName`	string \| null	Owner middle name
`email`	string \| null	Owner email address
`dateOfBirth`	string (date-time)	Owner date of birth
`percentageOwnership`	integer (int32)	Owner's percentage of business ownership
`phoneNumber`	string \| null	Owner phone number
`ssn`	string \| null	Owner SSN (masked: `XXX-XX-XXXX`)
`streetAddress`	string \| null	Owner street address (read-only)
`extendedAddress`	string \| null	Owner address line 2 (read-only)
`postalCode`	string \| null	Owner ZIP/postal code (read-only)
`locality`	string \| null	Owner city (read-only)
`state`	integer (int32)	Owner US state code (1–53)
`countryCodeAlpha3`	string \| null	ISO 3166-1 alpha-3 country code (read-only)
`ownerType`	integer (int32)	Owner classification type (1–4)

profileSettings object

Field	Type	Description
`financialAccountsPermissions.financialAccountsMaxNumber`	integer (int32)	Maximum number of internal financial accounts allowed
`financialAccountsPermissions.externalAccountsMaxNumber`	integer (int32)	Maximum number of linked external accounts allowed
`transferAmountLimits.achOutTransferAmountLimit`	integer (int64) \| null	Maximum ACH outbound transfer amount in cents
`transferAmountLimits.internalTransferAmountLimit`	integer (int64) \| null	Maximum internal transfer amount in cents
`loanOff`	boolean	Whether loan/funding features are disabled for this profile

employer object

Field	Type	Description
`id`	integer (int32)	Employer record identifier
`name`	string \| null	Employer name
`enabled`	boolean	Whether the employer integration is active
`date`	string (date-time)	Date the employer record was created

agreements array item object

Field	Type	Description
`name`	string \| null	Agreement name
`createdDate`	string (date-time)	Date the agreement was created
`acceptanceDate`	string (date-time) \| null	Date the account holder accepted the agreement

{
  "id": 1042,
  "createdDate": "2024-03-15T10:22:00Z",
  "updatedDate": "2024-11-01T08:45:00Z",
  "userProfileId": 8831,
  "step": 4,
  "accountHolderInformation": {
    "id": 501,
    "createdDate": "2024-03-15T10:22:00Z",
    "updatedDate": null,
    "email": "[email protected]",
    "givenName": "Jane",
    "familyName": "Doe",
    "middleName": "A",
    "phone": "+15555550101",
    "ssn": "XXX-XX-XXXX",
    "dateOfBirth": "1985-07-20T00:00:00Z",
    "streetAddress": "123 Main St",
    "extendedAddress": "Apt 4B",
    "postalCode": "30301",
    "locality": "Atlanta",
    "state": 10,
    "countryCodeAlpha3": "USA"
  },
  "businessAccountHolder": null,
  "isSubmitted": true,
  "accountHolderId": "ah_8f3a9c12e7d4b501",
  "nickName": "Jane",
  "cardProductId": "cp_7b2e1f45a3c8d906",
  "openApplicationId": null,
  "financialAccountId": "fa_2c9d4e78b1a5f310",
  "applicationStatus": 3,
  "bankingStatus": "Approved",
  "applicationDate": "2024-03-15T10:25:00Z",
  "approvalDate": "2024-03-16T09:00:00Z",
  "isDeleted": false,
  "isLocked": false,
  "isAccessLocked": false,
  "isMfaEnabled": true,
  "isOtpEnabled": false,
  "agentPayoutProfileId": null,
  "salesRepresentativeId": 12,
  "rewordType": 1,
  "isNew": false,
  "isExceptional": false,
  "profileSettings": {
    "financialAccountsPermissions": {
      "financialAccountsMaxNumber": 5,
      "externalAccountsMaxNumber": 3
    },
    "transferAmountLimits": {
      "achOutTransferAmountLimit": 1000000,
      "internalTransferAmountLimit": 500000
    },
    "loanOff": false
  },
  "applicationCreationType": "NeteviaAPI",
  "exceptionalTemplateId": null,
  "profileType": 1,
  "accountType": 1,
  "employer": null,
  "lockFinancialAccountId": null,
  "agreements": [
    {
      "name": "Terms of Service",
      "createdDate": "2024-01-01T00:00:00Z",
      "acceptanceDate": "2024-03-15T10:24:00Z"
    }
  ]
}

Error Codes

Code	When it happens
401	Token missing, expired, or invalid
403	Insufficient permissions to access the holder profile
500	Internal server error

Common Mistakes

Sending the request without a Bearer token or with an expired token will return a 401 error. Always refresh the token via POST /api/auth/refresh before it expires.
Expecting businessAccountHolder to be populated for personal accounts — for personal customers this field will be null, and personal data will be in accountHolderInformation instead.
Misinterpreting the state field as a two-letter abbreviation — the API returns an integer code (1–53) representing the US state, not a string.
Treating applicationStatus (integer) and bankingStatus (string) as the same field — they are distinct representations of application state and should be evaluated independently.

Related Endpoints

POST /api/auth/v2 — Obtain a Bearer token for authentication
POST /api/auth/refresh — Refresh an existing Bearer token
GET /v2/holder/business — Retrieve detailed business account holder profile
PUT /v2/holder — Update account holder information
GET /v2/financial-accounts — List financial accounts associated with the holder

Example

curl -X GET https://api.banking.netevia.dev/v2/holder \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"