Manage Online Merchant Application

post

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

Create or update a business customer profile in the Netevia banking platform.

Manage Online Merchant Application

This endpoint enables partners to create or update a business customer profile in the Netevia banking platform. It accepts full business and authorized-person details, including ownership structure, KYC data, and address information. On success, it returns a profile ID that can be used for subsequent operations.

Endpoint

POST /netevia/api/profile

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 through the Online Merchant Application flow. It is the primary boarding entry point for business profiles and must be called before creating financial accounts or issuing cards to the business. It supports partial updates to an existing profile by re-submitting with the same merchant identifier.

Request Body

Primary Applicant / Authorized Person

Field	Type	Required	Description
`email`	string (email)	Yes	Primary applicant email address
`givenName`	string	Yes	Applicant first name
`familyName`	string	Yes	Applicant last name
`middleName`	string	No	Applicant middle name
`phone`	string	Yes	Applicant phone number (10 digits)
`authorizedPersonTitle`	integer (enum)	Yes	Title of the authorized person. Values: 0=Unknown, 1=Mr, 2=Mrs, 3=Ms, 4=Miss, 5=Dr, 6=Prof
`percentageOwnership`	integer (0–100)	Yes	Ownership percentage held by the authorized person
`ssn`	string	Yes	Social Security Number. Format: `XXX-XX-XXXX` (no dashes in submission; 9-digit string)
`dateOfBirth`	string (date-time)	Yes	Applicant date of birth in ISO 8601 format
`streetAddress`	string	Yes	Applicant residential street address
`extendedAddress`	string	No	Applicant address line 2 (apt, suite, etc.)
`city`	string	Yes	Applicant city
`postalCode`	string	Yes	Applicant ZIP/postal code
`state`	integer (enum)	Yes	Applicant state as an integer (1=AL … 51=WY; see state enum)
`nickName`	string	No	Optional display nickname
`password`	string	No	Initial login password for the profile
`partnerId`	integer	No	Partner identifier; defaults to the authenticated partner if omitted
`cardProductId`	string	No	Card product to associate with this profile
`agentPayoutProfileId`	integer	Yes	Agent payout profile identifier
`salesRepresentativeId`	integer	Yes	Sales representative identifier
`merchantProfileId`	integer	No	Existing merchant profile ID for updates
`isRisk`	boolean	No	Flags the applicant as high risk

Business Information

Field	Type	Required	Description
`legalBusinessName`	string	Yes	Legal registered name of the business
`doingBusinessAsName`	string	Yes	Trade name / DBA name
`website`	string	No	Business website URL
`businessType`	integer (enum)	No	Business entity type. Values: 0=Unknown, 1=SoleProprietorship, 2=Partnership, 3=Corporation, 4=LLC
`businessPhone`	string	Yes	Business phone number (10 digits, no punctuation)
`businessStreetAddress`	string	Yes	Business street address
`businessExtendedAddress`	string	No	Business address line 2
`businessCity`	string	Yes	Business city
`businessPostalCode`	string	Yes	Business ZIP/postal code
`businessState`	integer (enum)	Yes	Business state as an integer (same enum as `state`)
`employerIdentificationNumber`	string	Yes	EIN in 9-digit format (no dashes)
`businessStartDate`	string (date-time)	No	Business incorporation or start date
`annualBusinessRevenue`	integer	No	Annual business revenue in cents (minimum 0)
`profileType`	integer (enum)	No	Profile type. Values: 0=Unknown, 1=Business, 2=Personal, 3=SubProfile
`applicationCreationType`	string (enum)	No	Application source channel. Values: `MobileApplication`, `OnlineBankingApplication`, `OnlineMerchantApplication`, `NeteviaBoardingApplication`, `BankingAPI`, `NeteviaAPI`
`payrollCustomer`	boolean	No	Indicates the business is a payroll customer
`primaryOwnerIsPrimaryAuthorizedPerson`	boolean	No	Set to `true` if the authorized person is also the primary owner

Owner Objects (each owner uses the same ownerrequest schema)

Field	Type	Required	Description
`primaryOwner`	object	No	Primary owner details (see owner schema below)
`secondaryOwner`	object	No	Secondary owner details
`owner3`	object	No	Third owner details
`owner4`	object	No	Fourth owner details
`thirdOwner`	object	No	Alias for third owner (Banking API extension)
`fourstOwner`	object	No	Alias for fourth owner (Banking API extension)

Owner Object Schema (ownerrequest)

Field	Type	Required	Description
`firstName`	string (max 255)	Yes	Owner first name
`lastName`	string (max 255)	Yes	Owner last name
`middleName`	string (max 255)	No	Owner middle name
`email`	string (email)	Yes	Owner email address
`homeAddress`	string	Yes	Owner residential street address
`extendedAddress`	string	No	Owner address line 2
`city`	string	Yes	Owner city
`state`	integer (enum)	Yes	Owner state as an integer
`zipCode`	string	Yes	Owner ZIP code (exactly 5 digits)
`homePhone`	string	Yes	Owner phone number (10 digits)
`percentageOwnership`	integer (25–100)	Yes	Ownership percentage (minimum 25)
`ssn`	string	Yes	Owner Social Security Number
`dob`	string (date-time)	Yes	Owner date of birth in ISO 8601 format

{
  "email": "[email protected]",
  "givenName": "Jane",
  "familyName": "Smith",
  "middleName": "A",
  "phone": "3055551234",
  "authorizedPersonTitle": 2,
  "percentageOwnership": 51,
  "ssn": "XXX-XX-XXXX",
  "dateOfBirth": "1980-04-15T00:00:00Z",
  "streetAddress": "123 Main St",
  "extendedAddress": "Apt 4B",
  "city": "Miami",
  "postalCode": "33101",
  "state": 10,
  "agentPayoutProfileId": 42,
  "salesRepresentativeId": 7,
  "legalBusinessName": "Acme Corp LLC",
  "doingBusinessAsName": "Acme Corp",
  "website": "https://www.acmecorp.com",
  "businessType": 4,
  "businessPhone": "3055559876",
  "businessStreetAddress": "456 Commerce Blvd",
  "businessCity": "Miami",
  "businessPostalCode": "33102",
  "businessState": 10,
  "employerIdentificationNumber": "123456789",
  "businessStartDate": "2015-06-01T00:00:00Z",
  "annualBusinessRevenue": 500000,
  "profileType": 1,
  "applicationCreationType": "NeteviaAPI",
  "payrollCustomer": false,
  "primaryOwnerIsPrimaryAuthorizedPerson": true
}

Response

200 OK

Field	Type	Description
`profileId`	integer	Unique identifier of the created or updated profile
`error`	string	Error message if the operation partially failed; `null` on full success

{
  "profileId": 10045,
  "error": null
}

Error Codes

Code	When it happens
400	Missing required fields, validation failure (e.g., invalid SSN format, EIN pattern mismatch, percentageOwnership out of range), or malformed date
401	Token missing, expired, or invalid
403	Insufficient permissions for the specified `partnerId` or `salesRepresentativeId`
404	Referenced `merchantProfileId` or `agentPayoutProfileId` not found
500	Internal server error

Common Mistakes

Submitting ssn with dashes (e.g., 123-45-6789) instead of the raw 9-digit string required by the pattern validation.
Setting percentageOwnership to a value below 25 for additional owners — the owner schema enforces a minimum of 25.
Omitting agentPayoutProfileId or salesRepresentativeId, which are required on the base profile request.
Providing businessPhone with punctuation or spaces — the field must be exactly 10 consecutive digits.
Using a state string (e.g., "FL") instead of the integer enum value (e.g., 10).
Supplying dateOfBirth or businessStartDate as a plain date string (e.g., "1980-04-15") instead of ISO 8601 date-time (e.g., "1980-04-15T00:00:00Z").

Related Endpoints

POST /api/auth/v2 — Obtain a Bearer token before calling this endpoint
POST /api/auth/refresh — Refresh an expiring Bearer token
GET /netevia/api/profile/{profileId} — Retrieve an existing business profile by ID
POST /netevia/api/financial-account — Create a financial account for the boarded business profile
POST /netevia/api/card — Issue a card to a business profile after boarding

Example

curl -X POST https://api.banking.netevia.dev/netevia/api/profile \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "givenName": "Jane",
    "familyName": "Smith",
    "phone": "3055551234",
    "authorizedPersonTitle": 2,
    "percentageOwnership": 51,
    "ssn": "123456789",
    "dateOfBirth": "1980-04-15T00:00:00Z",
    "streetAddress": "123 Main St",
    "city": "Miami",
    "postalCode": "33101",
    "state": 10,
    "agentPayoutProfileId": 42,
    "salesRepresentativeId": 7,
    "legalBusinessName": "Acme Corp LLC",
    "doingBusinessAsName": "Acme Corp",
    "businessPhone": "3055559876",
    "businessStreetAddress": "456 Commerce Blvd",
    "businessCity": "Miami",
    "businessPostalCode": "33102",
    "businessState": 10,
    "employerIdentificationNumber": "123456789",
    "profileType": 1,
    "applicationCreationType": "NeteviaAPI"
  }'

Body Params

thirdOwner

object

fourstOwner

object

phone

string

required

length ≥ 1

authorizedPersonTitle

int32

enum

required

Allowed:

percentageOwnership

int32

required

0 to 100

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.]*)*$

city

string

required

length ≥ 1

postalCode

string

required

length ≥ 1

state

int32

enum

required

legalBusinessName

string

required

length ≥ 1

doingBusinessAsName

string

required

length ≥ 1

website

string | null

businessType

int32

enum

Allowed:

businessPhone

string

required

length ≥ 1

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

businessStreetAddress

string

required

length ≥ 1

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

businessExtendedAddress

string | null

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

businessCity

string

required

length ≥ 1

businessPostalCode

string

required

length ≥ 1

businessState

int32

enum

required

employerIdentificationNumber

string

required

length ≥ 1

^(?!00\d{7}$)(?!\d{2}0000000$)(\d{2})?(\d{7})$

primaryOwnerIsPrimaryAuthorizedPerson

boolean

primaryOwner

object

secondaryOwner

object

owner3

object

owner4

object

businessStartDate

date-time | null

annualBusinessRevenue

int64 | null

≥ 0

profileType

int32

enum

Allowed:

applicationCreationType

string

enum

Allowed:

payrollCustomer

boolean

string

required

length ≥ 1

givenName

string

required

length ≥ 1

familyName

string

required

length ≥ 1

middleName

string | null

cardProductId

string | null

agentPayoutProfileId

int32

required

salesRepresentativeId

int32

required

merchantProfileId

int32 | null

isRisk

boolean | null

nickName

string | null

password

string | null

partnerId

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