Get linked Banking profile by mechantProfileID from Netevia

Get Linked Banking Profile by Merchant Profile ID

This endpoint retrieves a linked banking profile from Netevia using the specified merchantProfileId. It returns comprehensive details about the merchant's banking profile, including account holder information, application status, profile settings, and associated agreements. Use it to look up and manage the banking profile tied to a specific merchant identifier.

Endpoint

GET /netevia/profile/byMerchant/{merchantProfileId}

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 the banking profile linked to a known merchant profile ID, such as during onboarding verification, account management workflows, or when reconciling merchant records with their corresponding banking profile data. It is particularly useful for partners who maintain merchant profiles externally and need to cross-reference the associated banking profile state and application status.

Path Parameters

Parameter	Type	Required	Description
`merchantProfileId`	integer (int32)	Yes	The unique identifier of the merchant profile whose linked banking profile should be retrieved.

Response

200 OK

Field	Type	Description
`id`	integer	Internal ID of the banking profile record.
`createdDate`	string (date-time)	Timestamp when the profile was created.
`updatedDate`	string (date-time) \| null	Timestamp of the last profile update, if any.
`userProfileId`	integer	ID of the user profile associated with this banking profile.
`step`	integer (enum: 0–4)	Current onboarding step progress for this profile.
`accountHolderInformation`	object	Personal information of the individual account holder (see below).
`businessAccountHolder`	object	Business account holder details, populated for business profiles (see below).
`isSubmitted`	boolean \| null	Whether the banking application has been submitted.
`accountHolderId`	string \| null	External account holder ID.
`nickName`	string \| null	Display nickname for the profile.
`cardProductId`	string \| null	Associated card product ID.
`openApplicationId`	string \| null	ID of the open banking application, if any.
`financialAccountId`	string \| null	ID of the primary financial account linked to this profile.
`applicationStatus`	integer (enum: 0–4)	Numeric status of the banking application.
`bankingStatus`	string (enum)	Descriptive banking application status. One of: `New`, `Submitted`, `PendingUW`, `ApprovedUW`, `Closed`, `Cancelled`, `Pending_Review`, `Denied`, `Approved`, `Pending`, `InReview`, `AutoApprovedUW`.
`applicationDate`	string (date-time) \| null	Date the banking application was submitted.
`approvalDate`	string (date-time) \| null	Date the banking application was approved, if applicable.
`isDeleted`	boolean	Whether this profile has been soft-deleted.
`isLocked`	boolean	Whether the profile is locked.
`isAccessLocked`	boolean	Whether login access is locked (e.g., after multiple failed login attempts).
`isMfaEnabled`	boolean	Whether multi-factor authentication is enabled for this profile.
`isOtpEnabled`	boolean	Whether one-time password authentication is enabled.
`agentPayoutProfileId`	integer \| null	ID of the agent payout profile, if assigned.
`salesRepresentativeId`	integer \| null	ID of the assigned sales representative, if any.
`rewordType`	integer (enum: 1, 2, 4)	Reward type associated with this profile.
`isNew`	boolean \| null	Indicates if the profile is newly created.
`isExceptional`	boolean \| null	Indicates if the profile has exceptional/custom settings.
`profileSettings`	object	Profile-level settings including account limits and transfer limits (see below).
`applicationCreationType`	string (enum)	Channel through which the application was created. One of: `MobileApplication`, `OnlineBankingApplication`, `OnlineMerchantApplication`, `NeteviaBoardingApplication`, `BankingAPI`, `NeteviaAPI`.
`exceptionalTemplateId`	integer \| null	ID of the exceptional template applied to this profile, if any.
`profileType`	integer (enum: 0–3)	Profile type classification.
`accountType`	integer (enum: 1–5)	User account type classification.
`employer`	object \| null	Employer profile details if linked (see below).
`lockFinancialAccountId`	string \| null	ID of a locked financial account, if applicable.
`agreements`	array \| null	List of agreements associated with this profile (see below).

accountHolderInformation object

Field	Type	Description
`id`	integer	Record ID.
`createdDate`	string (date-time)	Creation timestamp.
`updatedDate`	string (date-time) \| null	Last update timestamp.
`email`	string \| null	Account holder 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 (returned as `XXX-XX-XXXX`).
`dateOfBirth`	string (date-time) \| null	Date of birth.
`streetAddress`	string \| null	Street address (read-only).
`extendedAddress`	string \| null	Extended address line (read-only).
`postalCode`	string \| null	ZIP/postal code (read-only).
`locality`	string \| null	City or locality (read-only).
`state`	integer	US state as numeric enum.
`countryCodeAlpha3`	string \| null	ISO 3166-1 alpha-3 country code (read-only).

businessAccountHolder object

Field	Type	Description
`id`	integer	Record ID.
`createdDate`	string (date-time)	Creation timestamp.
`updatedDate`	string (date-time) \| null	Last update timestamp.
`email`	string \| null	Primary contact email.
`givenName`	string \| null	First name of primary authorized person.
`familyName`	string \| null	Last name of primary authorized person.
`middleName`	string \| null	Middle name.
`phone`	string \| null	Primary authorized person phone number.
`ssn`	string \| null	Social Security Number (returned as `XXX-XX-XXXX`).
`dateOfBirth`	string (date-time) \| null	Date of birth of primary authorized person.
`streetAddress`	string \| null	Business street address (read-only).
`extendedAddress`	string \| null	Extended address line (read-only).
`postalCode`	string \| null	ZIP/postal code (read-only).
`locality`	string \| null	City or locality (read-only).
`state`	integer	US state as numeric enum.
`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)	Job title of the authorizing person.
`legalBusinessName`	string \| null	Legal registered business name.
`doingBusinessAsName`	string \| null	DBA (doing business as) name.
`website`	string \| null	Business website URL.
`businessType`	integer (enum: 0–4)	Type of business entity.
`businessPhone`	string \| null	Business phone number.
`employerIdentificationNumber`	string \| null	EIN (Employer Identification Number).
`primaryAuthorizedPersonId`	string \| null	External ID of the primary authorized person.
`primaryAuthorizedStreetAddress`	string \| null	Primary authorized person street address (read-only).
`primaryAuthorizedExtendedAddress`	string \| null	Primary authorized person extended address (read-only).
`primaryAuthorizedPostalCode`	string \| null	Primary authorized person postal code (read-only).
`primaryAuthorizedLocality`	string \| null	Primary authorized person city/locality (read-only).
`primaryAuthorizedState`	integer	Primary authorized person US state as numeric enum.
`businessStartDate`	string (date-time) \| null	Date the business was established.
`annualBusinessRevenue`	integer (int64) \| null	Annual business revenue in cents.
`payrollCustomer`	boolean \| null	Whether the business is a payroll customer.
`owners`	array \| null	List of business owners/beneficial owners (see owner object below).
`merchantProfileId`	integer \| null	Associated merchant profile ID.

owners array item object

Field	Type	Description
`id`	integer	Record ID.
`createdDate`	string (date-time)	Creation timestamp.
`updatedDate`	string (date-time) \| null	Last update timestamp.
`businessAccountId`	integer	ID of the business account this owner belongs to.
`givenName`	string \| null	Owner first name.
`familyName`	string \| null	Owner last name.
`middleName`	string \| null	Owner middle name.
`email`	string \| null	Owner email address.
`dateOfBirth`	string (date-time)	Owner date of birth.
`percentageOwnership`	integer	Ownership percentage held by this owner.
`phoneNumber`	string \| null	Owner phone number.
`ssn`	string \| null	Owner Social Security Number (returned as `XXX-XX-XXXX`).
`streetAddress`	string \| null	Owner street address (read-only).
`extendedAddress`	string \| null	Extended address line (read-only).
`postalCode`	string \| null	ZIP/postal code (read-only).
`locality`	string \| null	City or locality (read-only).
`state`	integer	US state as numeric enum.
`countryCodeAlpha3`	string \| null	ISO 3166-1 alpha-3 country code (read-only).
`ownerType`	integer (enum: 1–4)	Type classification of this owner.

profileSettings object

Field	Type	Description
`financialAccountsPermissions.financialAccountsMaxNumber`	integer	Maximum number of financial accounts allowed for this profile.
`financialAccountsPermissions.externalAccountsMaxNumber`	integer	Maximum number of external accounts allowed for this profile.
`transferAmountLimits.achOutTransferAmountLimit`	integer (int64) \| null	Maximum ACH outbound transfer amount.
`transferAmountLimits.internalTransferAmountLimit`	integer (int64) \| null	Maximum internal transfer amount.
`loanOff`	boolean	Whether lending/loan features are disabled for this profile.

employer object

Field	Type	Description
`id`	integer	Employer profile ID.
`name`	string \| null	Employer name.
`enabled`	boolean	Whether the employer profile is active.
`date`	string (date-time)	Date the employer profile was created or last updated.

agreements array item object

Field	Type	Description
`name`	string \| null	Name of the agreement.
`createdDate`	string (date-time)	Date the agreement was created.
`acceptanceDate`	string (date-time) \| null	Date the agreement was accepted by the customer, if accepted.

{
  "id": 1042,
  "createdDate": "2024-03-15T10:22:00Z",
  "updatedDate": "2024-05-01T08:45:00Z",
  "userProfileId": 7831,
  "step": 4,
  "accountHolderInformation": null,
  "businessAccountHolder": {
    "id": 501,
    "createdDate": "2024-03-15T10:22:00Z",
    "updatedDate": "2024-05-01T08:45:00Z",
    "email": "[email protected]",
    "givenName": "Jane",
    "familyName": "Smith",
    "middleName": null,
    "phone": "+15551234567",
    "ssn": "XXX-XX-XXXX",
    "dateOfBirth": "1980-06-12T00:00:00Z",
    "streetAddress": "123 Commerce Blvd",
    "extendedAddress": "Suite 400",
    "postalCode": "30301",
    "locality": "Atlanta",
    "state": 11,
    "countryCodeAlpha3": "USA",
    "percentageOwnership": 100,
    "authorizingPersonTitle": 1,
    "legalBusinessName": "Acme Corp LLC",
    "doingBusinessAsName": "Acme Corp",
    "website": "https://www.acmecorp.com",
    "businessType": 2,
    "businessPhone": "+14045556789",
    "employerIdentificationNumber": "XX-XXXXXXX",
    "primaryAuthorizedPersonId": "ap-abc123",
    "primaryAuthorizedStreetAddress": "123 Commerce Blvd",
    "primaryAuthorizedExtendedAddress": "Suite 400",
    "primaryAuthorizedPostalCode": "30301",
    "primaryAuthorizedLocality": "Atlanta",
    "primaryAuthorizedState": 11,
    "businessStartDate": "2015-01-01T00:00:00Z",
    "annualBusinessRevenue": 500000000,
    "payrollCustomer": true,
    "owners": [
      {
        "id": 201,
        "createdDate": "2024-03-15T10:22:00Z",
        "updatedDate": null,
        "businessAccountId": 501,
        "givenName": "Jane",
        "familyName": "Smith",
        "middleName": null,
        "email": "[email protected]",
        "dateOfBirth": "1980-06-12T00:00:00Z",
        "percentageOwnership": 100,
        "phoneNumber": "+15551234567",
        "ssn": "XXX-XX-XXXX",
        "streetAddress": "123 Commerce Blvd",
        "extendedAddress": "Suite 400",
        "postalCode": "30301",
        "locality": "Atlanta",
        "state": 11,
        "countryCodeAlpha3": "USA",
        "ownerType": 1
      }
    ],
    "merchantProfileId": 9988
  },
  "isSubmitted": true,
  "accountHolderId": "ah-xyz789",
  "nickName": "Acme Main Account",
  "cardProductId": "cp-00112233",
  "openApplicationId": null,
  "financialAccountId": "fa-aabbccdd",
  "applicationStatus": 2,
  "bankingStatus": "Approved",
  "applicationDate": "2024-03-15T10:30:00Z",
  "approvalDate": "2024-03-18T14:00:00Z",
  "isDeleted": false,
  "isLocked": false,
  "isAccessLocked": false,
  "isMfaEnabled": true,
  "isOtpEnabled": false,
  "agentPayoutProfileId": null,
  "salesRepresentativeId": 302,
  "rewordType": 1,
  "isNew": false,
  "isExceptional": false,
  "profileSettings": {
    "financialAccountsPermissions": {
      "financialAccountsMaxNumber": 5,
      "externalAccountsMaxNumber": 3
    },
    "transferAmountLimits": {
      "achOutTransferAmountLimit": 1000000,
      "internalTransferAmountLimit": 500000
    },
    "loanOff": false
  },
  "applicationCreationType": "NeteviaBoardingApplication",
  "exceptionalTemplateId": null,
  "profileType": 1,
  "accountType": 2,
  "employer": null,
  "lockFinancialAccountId": null,
  "agreements": [
    {
      "name": "Banking Terms and Conditions",
      "createdDate": "2024-03-15T10:22:00Z",
      "acceptanceDate": "2024-03-15T10:29:00Z"
    },
    {
      "name": "E-Sign Agreement",
      "createdDate": "2024-03-15T10:22:00Z",
      "acceptanceDate": "2024-03-15T10:29:00Z"
    }
  ]
}

Error Codes

Code	When it happens
400	Missing required fields or validation error (e.g., `merchantProfileId` is not a valid integer)
401	Token missing, expired, or invalid
403	Insufficient permissions to access this merchant profile's banking data
404	No banking profile found for the provided `merchantProfileId`
500	Internal server error

Common Mistakes

Passing a non-integer or string value for merchantProfileId — the parameter must be a valid 32-bit integer.
Using an expired or missing Bearer token — tokens last only 10 minutes; ensure you refresh before calling this endpoint.
Confusing merchantProfileId with userProfileId or id — this endpoint specifically looks up profiles by their merchant profile association, not the internal banking profile ID.
Expecting businessAccountHolder to be populated for personal profiles — this field is only present for business-type profiles; personal profiles use accountHolderInformation instead.

Related Endpoints

POST /api/auth/v2 — Obtain a Bearer token for authentication
POST /api/auth/refresh — Refresh an expiring Bearer token
GET /netevia/profile/{id} — Retrieve a banking profile by its internal profile ID
GET /netevia/profile/byUser/USERPROFILEID — Retrieve a banking profile by user profile ID

Example

curl -X GET https://api.banking.netevia.dev/netevia/profile/byMerchant/9988 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"