Send Primary, Authorized Person and Owners Data

This endpoint is used during business customer onboarding to submit identity and contact details for the primary authorized person and up to four beneficial owners associated with a business account. It records critical KYC (Know Your Customer) information required by Netevia to verify and activate the business account. Successful submission returns a boarding response confirming the profile ID and any processing changes.

Endpoint

POST /netevia/businessAccountHolder

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 when onboarding a new business customer onto the Netevia platform. It should be called after initial business registration to provide the authorizing person's personal details, business identification data, and ownership information for all beneficial owners holding 25% or more of the business. This step is required before a financial account can be opened for the business.

Request Body

Primary / Authorizing Person Fields

Business Fields

Beneficial Owner Fields (owner, owner2, owner3, owner4)

Each owner object supports up to four beneficial owners. All owner objects use the same schema. Each individual owner field set is optional at the top level, but if provided, all required sub-fields must be included.

{
  "email": "[email protected]",
  "givenName": "Jane",
  "familyName": "Doe",
  "middleName": "A",
  "phone": "3055550101",
  "ssn": "XXX-XX-XXXX",
  "dateOfBirth": "1980-04-15T00:00:00Z",
  "streetAddress": "100 Main St",
  "extendedAddress": "Suite 200",
  "city": "Miami",
  "postalCode": "33101",
  "state": 10,
  "authorizingPersonTitle": 2,
  "primaryAuthorizedStreetAddress": "100 Main St",
  "primaryAuthorizedExtendedAddress": "Suite 200",
  "primaryAuthorizedPostalCode": "33101",
  "primaryAuthorizedLocality": "Miami",
  "primaryAuthorizedState": 10,
  "legalBusinessName": "Acme Corporation LLC",
  "doingBusinessAsName": "Acme Corp",
  "employerIdentificationNumber": "123456789",
  "businessPhone": "3055550100",
  "percentageOwnership": 60,
  "businessType": 4,
  "website": "https://www.acmecorp.com",
  "businessStartDate": "2010-06-01T00:00:00Z",
  "annualBusinessRevenue": 500000,
  "payrollCustomer": false,
  "owner": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "[email protected]",
    "homePhone": "3055550202",
    "ssn": "XXX-XX-XXXX",
    "dob": "1975-08-20T00:00:00Z",
    "homeAddress": "200 Oak Ave",
    "city": "Miami",
    "state": 10,
    "zipCode": "33102",
    "percentageOwnership": 40
  }
}

Response

200 OK

The response is one of two schemas depending on whether a financial account was also opened during the boarding process.

boardingresponse

openfinancialaccountresponse (extends boardingresponse)

{
  "profileId": 100234,
  "success": true,
  "errors": null,
  "changeLog": [
    {
      "requestType": 1,
      "changes": "Business account holder profile created."
    }
  ]
}

Error Codes

Common Mistakes

• Sending ssn or dob in an incorrect format — SSN must match the exact regex pattern (no dashes in the raw value sent; use the unformatted 9-digit number), and dateOfBirth/dob must be ISO 8601 date-time strings.
• Providing an owner's percentageOwnership below 25 — the schema enforces a minimum of 25% per beneficial owner.
• Sending phone or businessPhone or homePhone with formatting characters (dashes, spaces, parentheses) — these fields must be exactly 10 consecutive digits.
• Omitting primaryAuthorizedStreetAddress, primaryAuthorizedPostalCode, primaryAuthorizedLocality, or primaryAuthorizedState — these are required even when they duplicate the authorizing person's residence address.
• Using a string state abbreviation (e.g., "FL") instead of the integer enum value (e.g., 10) for any state field.
• Submitting an employerIdentificationNumber with dashes — the EIN must be submitted as a 9-digit numeric string with no formatting characters.

Related Endpoints

• POST /netevia/businessCustomer — Create the initial business customer record before submitting account holder data
• POST /netevia/authorizedUser — Add an authorized subprofile user to an existing business account
• GET /netevia/businessAccountHolder/{profileId} — Retrieve submitted business account holder details for a given profile
• PUT /netevia/businessAccountHolder — Update existing business account holder information

Example

curl -X POST https://api.banking.netevia.dev/netevia/businessAccountHolder \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "givenName": "Jane",
    "familyName": "Doe",
    "phone": "3055550101",
    "ssn": "XXXXXXXXX",
    "dateOfBirth": "1980-04-15T00:00:00Z",
    "streetAddress": "100 Main St",
    "city": "Miami",
    "postalCode": "33101",
    "state": 10,
    "authorizingPersonTitle": 2,
    "primaryAuthorizedStreetAddress": "100 Main St",
    "primaryAuthorizedPostalCode": "33101",
    "primaryAuthorizedLocality": "Miami",
    "primaryAuthorizedState": 10,
    "legalBusinessName": "Acme Corporation LLC",
    "doingBusinessAsName": "Acme Corp",
    "employerIdentificationNumber": "123456789",
    "businessPhone": "3055550100",
    "percentageOwnership": 100,
    "businessType": 4
  }'