Send Personal Customer Data

post

https://api.banking.netevia.dev/netevia/personAccountHolder

Creates or updates a personal account holder's profile in the Netevia banking platform.

Send Personal Customer Data

The POST /netevia/personAccountHolder endpoint submits personal customer data to create or update an account holder profile for a personal banking customer. It supports both new customer onboarding and updates to existing personal profiles. On success, the API returns the assigned profile ID along with an optional financial account ID if a new financial account was opened during boarding.

Endpoint

POST /netevia/personAccountHolder

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 during personal customer onboarding to register a new account holder or to update an existing personal customer's profile information. This is the primary boarding endpoint for personal (non-business) customers and must be called before issuing payment cards or opening financial accounts. It is also used when a partner needs to update KYC data such as address, phone, or identity details for an existing personal customer.

Request Body

This endpoint accepts two request body schemas depending on operation type:

Create new personal customer — use personaccountholderrequest (includes all editpersonaccountholderrequest fields plus password)
Update existing personal customer — use editpersonaccountholderrequest

Field	Type	Required	Description
email	string (email)	Yes	Customer's email address
givenName	string	Yes	Customer's first name. Max 255 characters. Letters, hyphens, and spaces only
familyName	string	Yes	Customer's last name. Max 255 characters. Letters and spaces only
middleName	string	No	Customer's middle name. Max 255 characters. Letters and spaces only
phone	string	Yes	10-digit phone number (digits only, no formatting)
ssn	string	Yes	Social Security Number (digits only, no dashes). Must be a valid US SSN format
dateOfBirth	string (date-time)	Yes	Customer's date of birth in ISO 8601 format
streetAddress	string	Yes	Street address. Must include a street number followed by a street name
extendedAddress	string	No	Apartment, suite, or unit number
postalCode	string	Yes	5-digit US ZIP code
locality	string	Yes	City name
state	integer	Yes	US state as an integer enum value (1–53, mapping to US states and territories)
login	string	No	Custom login username. Between 6 and 40 characters
password	string	No	Customer's password. Required only when creating a new customer (not used for updates)
partnerId	integer	No	Partner identifier. Provided by Netevia during onboarding
agentUserName	string	No	Username of the referring agent, if applicable
agentPayoutId	integer	No	Payout ID associated with the referring agent
employerId	integer	No	Identifier of the customer's employer, used for EWA (Earned Wage Access) integrations
profileId	integer	No	Internal profile ID of the existing customer. Provide when updating an existing personal account holder

{
  "email": "[email protected]",
  "givenName": "Jane",
  "familyName": "Doe",
  "middleName": "Marie",
  "phone": "3055550123",
  "ssn": "XXX-XX-XXXX",
  "dateOfBirth": "1990-04-15T00:00:00Z",
  "streetAddress": "742 Evergreen Terrace",
  "extendedAddress": "Apt 3B",
  "postalCode": "33101",
  "locality": "Miami",
  "state": 10,
  "login": "janedoe90",
  "password": "SecureP@ss123",
  "partnerId": 1001
}

Response

200 OK

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

BoardingResponse (profile creation or update without new financial account):

Field	Type	Description
profileId	integer	The internal Netevia profile ID assigned to or matching the personal customer
success	boolean	`true` if the operation succeeded; `false` if errors occurred
errors	string	Error message details if `success` is `false`; otherwise `null`
changeLog	array	List of changes applied during the operation. Each entry contains `requestType` (integer enum) and `changes` (string description)

OpenFinancialAccountResponse (profile creation with simultaneous financial account opening, extends BoardingResponse):

Field	Type	Description
profileId	integer	The internal Netevia profile ID assigned to the personal customer
financialAccountId	string	ID of the newly created financial account
success	boolean	`true` if the operation succeeded
errors	string	Error message if `success` is `false`; otherwise `null`
changeLog	array	List of changes applied during boarding

{
  "profileId": 78432,
  "financialAccountId": "FA-00192837",
  "success": true,
  "errors": null,
  "changeLog": [
    {
      "requestType": 1,
      "changes": "Personal account holder profile created successfully."
    }
  ]
}

Error Codes

Code	When it happens
400	Missing required fields, invalid field format (e.g., malformed SSN, invalid ZIP code, state out of range), or validation pattern mismatch
401	Token missing, expired, or invalid
403	Insufficient permissions for the partner account
404	Existing profile not found when attempting an update
500	Internal server error

Common Mistakes

Submitting ssn with dashes or spaces — the field must contain digits only matching the valid US SSN pattern
Submitting phone with formatting characters (parentheses, dashes, spaces) — must be exactly 10 digits
Providing dateOfBirth in a non-ISO 8601 format such as MM/DD/YYYY — use YYYY-MM-DDT00:00:00Z
Using an out-of-range integer for state — valid values are 1 through 53 corresponding to US states and territories
Omitting password when creating a new customer — it is required for the create operation but not for updates
Including profileId without a valid existing customer record, which causes a 404 error on update attempts
Submitting postalCode with more or fewer than 5 digits — the field must match ^\d{5}$ exactly

Related Endpoints

POST /netevia/businessAccountHolder — Create or update a business account holder profile
POST /api/auth/v2 — Obtain a Bearer token for authentication
POST /api/auth/refresh — Refresh an expiring Bearer token
GET /netevia/personAccountHolder/{profileId} — Retrieve personal account holder details by profile ID
POST /netevia/financialAccount — Open a financial account for a personal customer after boarding

Example

curl -X POST https://api.banking.netevia.dev/netevia/personAccountHolder \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "givenName": "Jane",
    "familyName": "Doe",
    "phone": "3055550123",
    "ssn": "123456789",
    "dateOfBirth": "1990-04-15T00:00:00Z",
    "streetAddress": "742 Evergreen Terrace",
    "extendedAddress": "Apt 3B",
    "postalCode": "33101",
    "locality": "Miami",
    "state": 10,
    "login": "janedoe90",
    "password": "SecureP@ss123",
    "partnerId": 1001
  }'

Body Params

highNoteProfileId

int32 | null

partnerId

int32 | null

agentUserName

string | null

agentPayoutId

int32 | null

string

required

length ≥ 1

givenName

string

required

length between 1 and 255

[A-z-\s]+

familyName

string

required

length between 1 and 255

[A-z\s]+

middleName

string | null

[A-z\s]+

phone

string

required

length ≥ 1

^(\d|\*){10}$

ssn

string

required

length ≥ 1

^(?!(666|9\d{2}))(?:0[1-9]\d|00[1-9]|[1-8]\d{2})(?:0[1-9]|[1-9]\d)(?!0000)\d{4}$

dateOfBirth

date-time

required

streetAddress

string

required

length ≥ 1

^\d+([\s/-]?[A-z\d/\]{1,2}|[A-z\d]+)?(?:\s[A-z\d'_-]+)+$

extendedAddress

string | null

^[a-zA-Z\d',. \-#]+(([',. \-#][a-zA-Z ])?[a-zA-Z.]*)*$

postalCode

string

required

length ≥ 1

^\d{5}$

locality

string

required

length ≥ 1

state

int32

enum

required

string | null

employerId

int32 | null

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

content-type

string

enum

Defaults to application/json

Generated from available request content types

Allowed:

Response

Language

Credentials

Bearer

JWT

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

text/plain

application/json

text/json