Search Business Profiles

This endpoint retrieves a paginated list of business profiles from the Netevia database based on specified query parameters. Partners can filter results by business name, owner details, location, tax identifiers, application status, and more. The response includes comprehensive business and account holder information for each matched profile.

Endpoint

GET /netevia/searchBusinessProfiles

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 you need to look up one or more business customer profiles — for example, to locate a specific business by name or EIN, audit onboarding status, or retrieve profiles belonging to a particular partner or agent. It is also useful for support workflows where a customer-facing representative needs to search by owner name, email, or last 4 digits of a card. All filtering is done via query parameters; no request body is required.

Query Parameters

Parameter	Type	Required	Description
skip	integer (int32)	No	Number of records to skip for pagination. Default: `0`
count	integer (int32)	No	Maximum number of records to return. Default: `20`
dba	string	No	Filter by "doing business as" name
legalName	string	No	Filter by legal business name
firstName	string	No	Filter by primary authorized person's first name
lastName	string	No	Filter by primary authorized person's last name
email	string	No	Filter by email address
city	string	No	Filter by city
state	integer (int32)	No	Filter by US state (enum value 1–53, representing each state/territory)
zip	string	No	Filter by ZIP/postal code
ssn	string	No	Filter by Social Security Number (format: XXX-XX-XXXX)
ein	string	No	Filter by Employer Identification Number
mid	integer (int32)	No	Filter by merchant profile ID
status	integer (int32)	No	Filter by bank application status (enum: 0–4)
bankingStatus	string	No	Filter by banking application status. Values: `New`, `Submitted`, `PendingUW`, `ApprovedUW`, `Closed`, `Cancelled`, `Pending_Review`, `Denied`, `Approved`, `Pending`, `InReview`, `AutoApprovedUW`
agentId	integer (int32)	No	Filter by agent ID
isoId	integer (int32)	No	Filter by ISO ID
last4	string	No	Filter by last 4 digits of a card
partnerId	integer (int32)	No	Filter by partner ID
userId	integer (int32)	No	Filter by user ID
payrollCustomer	boolean	No	Filter to payroll customers only (`true`) or non-payroll customers (`false`)
finAccountNumber	integer (int64)	No	Filter by financial account number

Response

200 OK

The response wraps a paginated array of business profile records.

Field	Type	Description
totalCount	integer	Total number of records matching the query
errorMessage	string \| null	Error message if the request encountered a non-fatal issue
cursor	string \| null	Pagination cursor for fetching the next page
records	array	Array of `primaryprofileresponse` objects (see below)

records[] — Primary Profile Response Fields

Field	Type	Description
id	integer	Internal profile ID
createdDate	string (date-time)	Profile creation timestamp
updatedDate	string (date-time) \| null	Last update timestamp
userProfileId	integer	Associated user profile ID
step	integer (enum 0–4)	Onboarding step completed so far
accountHolderInformation	object	Personal information of the primary account holder (see below)
businessAccountHolder	object	Business-specific account holder details (see below)
isSubmitted	boolean \| null	Whether the application has been submitted
accountHolderId	string \| null	External account holder identifier
nickName	string \| null	Display nickname for the profile
cardProductId	string \| null	Associated card product ID
openApplicationId	string \| null	Open application identifier
financialAccountId	string \| null	Primary financial account ID
applicationStatus	integer (enum 0–4)	Bank application status code
bankingStatus	string	Banking application status string (e.g., `Approved`, `PendingUW`)
applicationDate	string (date-time) \| null	Date the application was submitted
approvalDate	string (date-time) \| null	Date the application was approved
isDeleted	boolean	Whether the profile has been soft-deleted
isLocked	boolean	Whether the profile is locked
isAccessLocked	boolean	Whether login access is locked (e.g., after repeated failed login attempts)
isMfaEnabled	boolean	Whether multi-factor authentication is enabled
isOtpEnabled	boolean	Whether one-time password authentication is enabled
agentPayoutProfileId	integer \| null	Agent payout profile ID
salesRepresentativeId	integer \| null	Sales representative ID
rewordType	integer (enum: 1, 2, 4)	Reward type assigned to the profile
isNew	boolean \| null	Whether the profile is newly created
isExceptional	boolean \| null	Whether the profile is flagged as exceptional
profileSettings	object	Profile-level settings (financial account limits, transfer limits)
applicationCreationType	string	How the application was created (e.g., `BankingAPI`, `NeteviaAPI`, `MobileApplication`)
exceptionalTemplateId	integer \| null	Exceptional template ID if applicable
profileType	integer (enum 0–3)	Profile type classification
accountType	integer (enum 1–5)	User account type
employer	object \| null	Employer profile details if the customer is linked to an employer
lockFinancialAccountId	string \| null	Financial account ID used for locking
agreements	array \| null	List of accepted agreements (name, createdDate, acceptanceDate)

accountHolderInformation — Personal Information Fields

Field	Type	Description
id	integer	Record ID
createdDate	string (date-time)	Record creation timestamp
updatedDate	string (date-time) \| null	Record update timestamp
email	string \| null	Email address
givenName	string \| null	First name
familyName	string \| null	Last name
middleName	string \| null	Middle name
phone	string \| null	Phone number
ssn	string \| null	Social Security Number (masked in display: XXX-XX-XXXX)
dateOfBirth	string (date-time) \| null	Date of birth
streetAddress	string \| null	Street address (read-only)
extendedAddress	string \| null	Address line 2 (read-only)
postalCode	string \| null	Postal/ZIP code (read-only)
locality	string \| null	City/locality (read-only)
state	integer	US state enum value
countryCodeAlpha3	string \| null	ISO 3166-1 alpha-3 country code (read-only)

businessAccountHolder — Business Account Holder Fields

Field	Type	Description
id	integer	Record ID
createdDate	string (date-time)	Record creation timestamp
updatedDate	string (date-time) \| null	Record update timestamp
email	string \| null	Business email address
givenName	string \| null	Primary authorized person's first name
familyName	string \| null	Primary authorized person's last name
middleName	string \| null	Primary authorized person's middle name
phone	string \| null	Primary authorized person's phone number
ssn	string \| null	Primary authorized person's SSN (masked: XXX-XX-XXXX)
dateOfBirth	string (date-time) \| null	Primary authorized person's date of birth
streetAddress	string \| null	Business street address (read-only)
extendedAddress	string \| null	Business address line 2 (read-only)
postalCode	string \| null	Business postal code (read-only)
locality	string \| null	Business city/locality (read-only)
state	integer	Business US state enum value
countryCodeAlpha3	string \| null	ISO 3166-1 alpha-3 country code (read-only)
percentageOwnership	integer	Ownership percentage of the primary authorized person
authorizingPersonTitle	integer (enum 0–6)	Title of the authorizing person
legalBusinessName	string \| null	Legal name of the business
doingBusinessAsName	string \| null	DBA name
website	string \| null	Business website URL
businessType	integer (enum 0–4)	Business entity type
businessPhone	string \| null	Business phone number
employerIdentificationNumber	string \| null	Federal EIN
primaryAuthorizedPersonId	string \| null	Identifier of the primary authorized person
primaryAuthorizedStreetAddress	string \| null	Primary authorized person's street address (read-only)
primaryAuthorizedExtendedAddress	string \| null	Primary authorized person's address line 2 (read-only)
primaryAuthorizedPostalCode	string \| null	Primary authorized person's postal code (read-only)
primaryAuthorizedLocality	string \| null	Primary authorized person's city (read-only)
primaryAuthorizedState	integer	Primary authorized person's US state enum value
businessStartDate	string (date-time) \| null	Date the business was established
annualBusinessRevenue	integer (int64) \| null	Annual revenue of the business in cents or whole dollars
payrollCustomer	boolean \| null	Whether this business uses payroll services
owners	array \| null	Array of additional business owners (see owner fields below)
merchantProfileId	integer \| null	Associated merchant profile ID

{
  "totalCount": 2,
  "errorMessage": null,
  "cursor": null,
  "records": [
    {
      "id": 1042,
      "createdDate": "2024-03-15T10:22:00Z",
      "updatedDate": "2024-05-01T08:45:00Z",
      "userProfileId": 8801,
      "step": 4,
      "accountHolderInformation": {
        "id": 210,
        "createdDate": "2024-03-15T10:22:00Z",
        "updatedDate": null,
        "email": "[email protected]",
        "givenName": "Jane",
        "familyName": "Smith",
        "middleName": null,
        "phone": "+15555550100",
        "ssn": "XXX-XX-XXXX",
        "dateOfBirth": "1980-06-12T00:00:00Z",
        "streetAddress": "123 Main St",
        "extendedAddress": "Suite 400",
        "postalCode": "30301",
        "locality": "Atlanta",
        "state": 11,
        "countryCodeAlpha3": "USA"
      },
      "businessAccountHolder": {
        "id": 310,
        "createdDate": "2024-03-15T10:22:00Z",
        "updatedDate": "2024-05-01T08:45:00Z",
        "email": "[email protected]",
        "givenName": "Jane",
        "familyName": "Smith",
        "middleName": null,
        "phone": "+15555550100",
        "ssn": "XXX-XX-XXXX",
        "dateOfBirth": "1980-06-12T00:00:00Z",
        "streetAddress": "123 Main St",
        "extendedAddress": "Suite 400",
        "postalCode": "30301",
        "locality": "Atlanta",
        "state": 11,
        "countryCodeAlpha3": "USA",
        "percentageOwnership": 100,
        "authorizingPersonTitle": 1,
        "legalBusinessName": "Acme Corp LLC",
        "doingBusinessAsName": "Acme Corp",
        "website": "https://acmecorp.com",
        "businessType": 2,
        "businessPhone": "+14045550199",
        "employerIdentificationNumber": "XX-XXXXXXX",
        "primaryAuthorizedPersonId": "auth-person-abc123",
        "primaryAuthorizedStreetAddress": "123 Main St",
        "primaryAuthorizedExtendedAddress": "Suite 400",
        "primaryAuthorizedPostalCode": "30301",
        "primaryAuthorizedLocality": "Atlanta",
        "primaryAuthorizedState": 11,
        "businessStartDate": "2015-01-01T00:00:00Z",
        "annualBusinessRevenue": 500000,
        "payrollCustomer": false,
        "owners": [],
        "merchantProfileId": 4400
      },
      "isSubmitted": true,
      "accountHolderId": "acc-holder-xyz789",
      "nickName": "Acme Corp",
      "cardProductId": "card-prod-001",
      "openApplicationId": null,
      "financialAccountId": "fin-acct-001",
      "applicationStatus": 2,
      "bankingStatus": "Approved",
      "applicationDate": "2024-03-15T10:22:00Z",
      "approvalDate": "2024-03-20T14:00:00Z",
      "isDeleted": false,
      "isLocked": false,
      "isAccessLocked": false,
      "isMfaEnabled": true,
      "isOtpEnabled": false,
      "agentPayoutProfileId": null,
      "salesRepresentativeId": 55,
      "rewordType": 1,
      "isNew": false,
      "isExceptional": false,
      "profileSettings": {
        "financialAccountsPermissions": {
          "financialAccountsMaxNumber": 5,
          "externalAccountsMaxNumber": 3
        },
        "transferAmountLimits": {
          "achOutTransferAmountLimit": 50000,
          "internalTransferAmountLimit": 100000
        },
        "loanOff": false
      },
      "applicationCreationType": "NeteviaAPI",
      "exceptionalTemplateId": null,
      "profileType": 1,
      "accountType": 2,
      "employer": null,
      "lockFinancialAccountId": null,
      "agreements": [
        {
          "name": "Terms of Service",
          "createdDate": "2024-03-15T10:22:00Z",
          "acceptanceDate": "2024-03-15T10:25:00Z"
        }
      ]
    }
  ]
}

Error Codes

Code	When it happens
400	Missing required fields or validation error
401	Token missing, expired, or invalid
403	Insufficient permissions
404	Resource not found
500	Internal server error

Common Mistakes

Passing an invalid state integer value — the state enum maps integers 1–53 to US states and territories; values outside this range will cause a validation error or return no results.
Not paginating correctly — the default count is 20; use skip and count together to page through large result sets rather than relying on the default.
Searching by ssn or ein without proper formatting — pass raw digits or the standard formatted string exactly as stored; mismatched formats will return no results.
Using bankingStatus values not in the allowed enum — only exact string values like Approved, PendingUW, Denied, etc. are accepted; typos or casing differences will be rejected.
Omitting the Authorization header entirely — every request must include a valid Bearer token.

Related Endpoints

POST /api/auth/v2 — Obtain a Bearer token for authentication
POST /api/auth/refresh — Refresh an expiring Bearer token
GET /netevia/getBusinessProfile/{id} — Retrieve a single business profile by ID
POST /netevia/createBusinessProfile — Create a new business profile
PUT /netevia/updateBusinessProfile/{id} — Update an existing business profile

Example

curl -X GET "https://api.banking.netevia.dev/netevia/searchBusinessProfiles?legalName=Acme%20Corp&bankingStatus=Approved&count=10&skip=0" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"