Create and submit banking services application

Time	Status	User Agent
Retrieving recent requests…

Create and Submit Banking Services Application

Submits a complete business banking services application on behalf of a merchant. The request bundles business information, the primary authorized person's identity and ownership details, and up to four additional owners. Upon success, the API returns a profileId that is used to track notes and status throughout the underwriting and approval process.

Endpoint

POST /api/v1/banking/submit

Authentication

Basic HTTP Authentication required.
Encode username:password in Base64 and pass in the Authorization header:

Authorization: Basic {base64(username:password)}

When to use

Use this endpoint during the Instant Funding onboarding flow after a merchant has been created and approved in the standard boarding pipeline. It captures the merchant's banking details, business structure, and owner KYC information required by the banking provider. After submission, poll GET /api/v1/banking/status and GET /api/v1/banking/notes/{profileId} to track the application.

Request Body

Field	Type	Required	Description
agentPayoutProfileId	integer (int32)	No	Payout profile ID for the agent associated with this banking application
merchantProfileId	integer (int32)	No	Merchant profile ID from the standard boarding system
businessInfo	BankingBusinessInfo	No	Business details (see nested fields below)
businessInfo.businessType	string (enum)	No	`CORPORATION`, `PARTNERSHIP`, `SOLE_PROPRIETORSHIP`, `NON_PROFIT`, `LLC`
businessInfo.legalName	string	Yes	Legal name of the business
businessInfo.dba	string	Yes	Doing Business As name
businessInfo.website	string	No	Business website URL
businessInfo.phone	string	Yes	Business phone number
businessInfo.address	string	Yes	Street address
businessInfo.extendedAddress	string	No	Suite, unit, floor, etc.
businessInfo.city	string	Yes	City
businessInfo.state	string (enum)	Yes	Full state name, e.g. `California`, `Texas`
businessInfo.zip	string	Yes	5-digit ZIP code
businessInfo.clientType	string (enum)	Yes	`NotSet`, `ISO`, `Merchant`, `StandaloneClient`
businessInfo.businessStartDate	string (date-time)	No	Date the business was established (ISO 8601)
businessInfo.annualBusinessRevenue	integer (int64)	No	Annual revenue in whole dollars (minimum 0)
businessInfo.payrollCustomer	boolean	No	Whether the business uses payroll services
primaryAuthorizedPerson	BankingPrimaryAuthorizedPerson	No	Primary authorized person details
primaryAuthorizedPerson.title	string (enum)	No	`PRESIDENT`, `VICE_PRESIDENT`, `TREASURER`, `OWNER`, `CEO`, `CFO`, `COO`
primaryAuthorizedPerson.ein	string	Yes	Employer Identification Number
primaryAuthorizedPerson.firstName	string	Yes	First name
primaryAuthorizedPerson.middleName	string	No	Middle name
primaryAuthorizedPerson.lastName	string	Yes	Last name
primaryAuthorizedPerson.dob	string (date-time)	Yes	Date of birth (ISO 8601)
primaryAuthorizedPerson.email	string	Yes	Email address
primaryAuthorizedPerson.phone	string	Yes	Phone number
primaryAuthorizedPerson.address	string	Yes	Street address
primaryAuthorizedPerson.extendedAddress	string	No	Suite, unit, etc.
primaryAuthorizedPerson.city	string	Yes	City
primaryAuthorizedPerson.state	string (enum)	Yes	Full state name
primaryAuthorizedPerson.zip	string	Yes	5-digit ZIP code
primaryAuthorizedPerson.ssn	string	Yes	Social Security Number (9 digits, no dashes)
primaryAuthorizedPerson.ownership	integer (int32)	No	Ownership percentage (0–100)
owner1IsPrimaryAuthorizedPerson	boolean	No	Set to `true` if owner1 and the primary authorized person are the same individual
owner1	BankingOwner	No	First additional owner (same fields as owner below)
owner2	BankingOwner	No	Second additional owner
owner3	BankingOwner	No	Third additional owner
owner4	BankingOwner	No	Fourth additional owner
owner1.firstName	string	Yes (if owner1 present)	First name
owner1.lastName	string	Yes (if owner1 present)	Last name
owner1.dob	string (date-time)	Yes (if owner1 present)	Date of birth (ISO 8601)
owner1.email	string	Yes (if owner1 present)	Email address
owner1.phone	string	Yes (if owner1 present)	Phone number
owner1.address	string	Yes (if owner1 present)	Street address
owner1.city	string	Yes (if owner1 present)	City
owner1.state	string (enum)	Yes (if owner1 present)	Full state name
owner1.zip	string	Yes (if owner1 present)	5-digit ZIP code
owner1.ssn	string	Yes (if owner1 present)	Social Security Number (9 digits)
owner1.ownership	integer (int32)	No	Ownership percentage (0–100)

{
  "agentPayoutProfileId": 1045,
  "merchantProfileId": 30872,
  "businessInfo": {
    "businessType": "LLC",
    "legalName": "Sunrise Retail LLC",
    "dba": "Sunrise Gift Shop",
    "website": "https://www.sunrisegiftshop.com",
    "phone": "8005550142",
    "address": "4400 Commerce Blvd",
    "extendedAddress": "Suite 210",
    "city": "Phoenix",
    "state": "Arizona",
    "zip": "85001",
    "clientType": "Merchant",
    "businessStartDate": "2018-06-01T00:00:00Z",
    "annualBusinessRevenue": 480000,
    "payrollCustomer": false
  },
  "primaryAuthorizedPerson": {
    "title": "OWNER",
    "ein": "471234567",
    "firstName": "Maria",
    "lastName": "Gonzalez",
    "dob": "1980-03-22T00:00:00Z",
    "email": "[email protected]",
    "phone": "6025550187",
    "address": "1122 Desert Way",
    "city": "Phoenix",
    "state": "Arizona",
    "zip": "85002",
    "ssn": "456781234",
    "ownership": 100
  },
  "owner1IsPrimaryAuthorizedPerson": true
}

Response

200 OK

Field	Type	Description
data.profileId	integer	Newly created banking application profile ID — use this to check notes and status
data.error	string	Error detail if the profile could not be created
requestId	integer	Echo of the internal request ID
success	boolean	`true` if the application was submitted successfully
error	string	Top-level error message if `success` is `false`
validationErrors	array	Field-level validation errors with `field` and `error` properties

{
  "data": {
    "profileId": 7823,
    "error": null
  },
  "requestId": 98205,
  "success": true,
  "error": null,
  "validationErrors": []
}

Error Codes

Code	When it happens
400	Required fields are missing or fail validation (e.g., invalid state enum, bad SSN format)
401	Invalid or missing Basic Auth credentials
403	User does not have permission for this operation
500	Internal server error while creating or submitting the profile

Common Mistakes

Sending SSN with dashes (123-45-6789) instead of 9 consecutive digits (123456789).
Using state abbreviations (AZ) instead of the full enum name (Arizona) — the API rejects abbreviations.
Omitting clientType from businessInfo — it is required even though it defaults conceptually to Merchant.
Setting owner1IsPrimaryAuthorizedPerson: true but still populating separate owner1 fields that conflict with the primary authorized person — use one or the other.
Not storing the returned profileId — it is required to check status and notes after submission.

Related Endpoints

GET /api/v1/banking/status — Check the approval status of the submitted application
GET /api/v1/banking/notes/{profileId} — Retrieve reviewer notes for the application
POST /api/v1/banking/submit/personal — Alternative for personal/sole-proprietor banking applications

Example

curl -X POST https://hq.staging.netevia.dev/api/v1/banking/submit \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "agentPayoutProfileId": 1045,
    "merchantProfileId": 30872,
    "businessInfo": {
      "businessType": "LLC",
      "legalName": "Sunrise Retail LLC",
      "dba": "Sunrise Gift Shop",
      "phone": "8005550142",
      "address": "4400 Commerce Blvd",
      "city": "Phoenix",
      "state": "Arizona",
      "zip": "85001",
      "clientType": "Merchant"
    },
    "primaryAuthorizedPerson": {
      "title": "OWNER",
      "ein": "471234567",
      "firstName": "Maria",
      "lastName": "Gonzalez",
      "dob": "1980-03-22T00:00:00Z",
      "email": "[email protected]",
      "phone": "6025550187",
      "address": "1122 Desert Way",
      "city": "Phoenix",
      "state": "Arizona",
      "zip": "85002",
      "ssn": "456781234",
      "ownership": 100
    },
    "owner1IsPrimaryAuthorizedPerson": true
  }'