User Registration for Business Accounts

This endpoint registers a new business customer account on the Netevia Banking platform. It accepts business details, primary authorized person information, optional additional owners, and login credentials, then performs identity and compliance verification in real time. On success, it returns a profile ID and optionally a financial account ID if an account was opened during onboarding.

Endpoint

POST /api/users

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 handles the full registration flow: capturing legal business information, verifying the primary authorized person's identity, recording any additional beneficial owners with 25%+ ownership, and creating login credentials. This is the required first step before issuing cards, opening financial accounts, or enabling any business banking features for a new business customer.

Request Body

Top-level fields

Business Details (businessDetails)

Primary Authorized Person (primaryAythorizedPerson)

Additional Owner fields (owner, owner2, owner3, owner4)

{
  "businessDetails": {
    "legalBusinessName": "Acme Logistics LLC",
    "doingBusinessAsName": "Acme Logistics",
    "businessPhone": "3055550100",
    "website": "https://www.acmelogistics.com",
    "businessType": 2,
    "taxId": "123456789",
    "streetAddress": "200 Brickell Ave",
    "extendedAddress": "Suite 400",
    "city": "Miami",
    "postalCode": "33131",
    "state": 10,
    "businessStartDate": "2015-03-01T00:00:00Z",
    "annualBusinessRevenue": 2500000,
    "payrollCustomer": false
  },
  "primaryAythorizedPerson": {
    "givenName": "Jane",
    "familyName": "Smith",
    "middleName": "A",
    "email": "[email protected]",
    "phone": "3055550101",
    "ssn": "XXX-XX-XXXX",
    "dateOfBirth": "1985-06-15T00:00:00Z",
    "streetAddress": "101 Main St",
    "extendedAddress": "Apt 5B",
    "city": "Miami",
    "postalCode": "33101",
    "state": 10,
    "percentageOwnership": 60,
    "authorizingPersonTitle": 5
  },
  "owner": {
    "firstName": "Robert",
    "lastName": "Jones",
    "email": "[email protected]",
    "homePhone": "3055550102",
    "ssn": "XXX-XX-XXXX",
    "dob": "1979-11-20T00:00:00Z",
    "homeAddress": "500 Ocean Dr",
    "city": "Miami Beach",
    "zipCode": "33139",
    "state": 10,
    "percentageOwnership": 40
  },
  "login": "jane.smith.acme",
  "password": "S3cur3P@ssw0rd!",
  "partnerId": 1042
}

Response

200 OK

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

Base response (boardingresponse)

Extended response (openfinancialaccountresponse) — includes all base fields plus:

{
  "profileId": 98321,
  "success": true,
  "errors": null,
  "financialAccountId": "fa_7e3a1c9b4d2f",
  "changeLog": [
    {
      "requestType": 1,
      "changes": "Business profile created."
    },
    {
      "requestType": 3,
      "changes": "Primary authorized person verified."
    }
  ]
}

Error Codes

Common Mistakes

• Sending ssn with dashes (e.g., XXX-XX-XXXX) — the field requires 9 raw digits with no formatting characters.
• Omitting primaryAythorizedPerson (note the intentional typo in the field name: primaryAythorizedPerson, not primaryAuthorizedPerson) — this will cause a 400 validation error.
• Providing a percentageOwnership below 25 for owner, owner2, owner3, or owner4 — each additional owner must hold at least 25% to qualify as a beneficial owner.
• Sending state as a two-letter abbreviation (e.g., "FL") instead of the required integer enum value.
• Sending postalCode or zipCode as an integer instead of a string — both fields must be strings matching the 5-digit pattern.
• Formatting businessPhone or homePhone with dashes or parentheses — only 10 consecutive digits are accepted.

Related Endpoints

• POST /api/auth/v2 — Obtain a Bearer token required to authenticate this request
• POST /api/auth/refresh — Refresh an expiring Bearer token
• GET /api/users/{profileId} — Retrieve profile details for a registered business customer
• POST /api/users/{profileId}/financial-accounts — Open a financial account for an existing business customer
• POST /api/users/{profileId}/subprofiles — Add an authorized user (subprofile) to a business customer account

Example

curl -X POST https://api.banking.netevia.dev/api/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "businessDetails": {
      "legalBusinessName": "Acme Logistics LLC",
      "doingBusinessAsName": "Acme Logistics",
      "businessPhone": "3055550100",
      "businessType": 2,
      "taxId": "123456789",
      "streetAddress": "200 Brickell Ave",
      "extendedAddress": "Suite 400",
      "city": "Miami",
      "postalCode": "33131",
      "state": 10
    },
    "primaryAythorizedPerson": {
      "givenName": "Jane",
      "familyName": "Smith",
      "email": "[email protected]",
      "phone": "3055550101",
      "ssn": "123456789",
      "dateOfBirth": "1985-06-15T00:00:00Z",
      "streetAddress": "101 Main St",
      "city": "Miami",
      "postalCode": "33101",
      "state": 10,
      "percentageOwnership": 100,
      "authorizingPersonTitle": 5
    },
    "login": "jane.smith.acme",
    "password": "S3cur3P@ssw0rd!",
    "partnerId": 1042
  }'