Applications - Partners

Hi there! Welcome to Dex, Forte's latest and greatest payments application. With Dex, you can view, create, and manage all your transaction data—including customers, payment methods, addresses, and schedules—in one convenient place. You can also view and maintain your merchant account, keep track of your funding entries, resolve disputed transactions, and generate API credentials to connect Dex with your third-party applications.

Overview

Forte’s Merchant Application Portal provides Partners with a streamlined solution for quickly onboarding merchants to your payments platform. Whether you need a simple payments gateway to connect your merchant to a credit card processor or a full-service, multichannel payment processing solution—we’ve got you covered. Partners can capture merchant applications via two different integration channels:

Connecting your platform to Forte via the applications resource in our REST API
Sending branded applications to merchants via email through the Dex Merchant Application Portal

With either integration method, you have the ability pick and choose from Forte’s value-added services (e.g., Forte Verify or Account Updater) and enjoy faster decisioning with Forte’s proprietary, automated underwriting checks.

Using Forte's Underwriting Services

Underwriting can be an expensive, risky, time-consuming hassle. We've eliminated that headache with our expedited underwriting protocol. We run each application you submit to Forte through a sequenced series of automated checks with a combination of services to validate a merchant's criminal, business, and credit histories. Any result that falls outside the threshold of acceptable risk is sent to our Credit Team for manual decisioning. Merchant applications that pass each check are automatically approved and immediately sent to our Enrollment Team for onboarding. This streamlined process creates a faster, more consistent onboarding process so that merchants can be up and running within days instead of weeks.

Partners that prefer to conduct their own underwriting or already have an underwriting solution in place can opt out of these checks. For these types of partner accounts, all applications submitted to Forte are automatically forwarded directly to our Enrollment Team for onboarding. While this provides an even faster onboarding solution, the partner assumes all legal and financial liability for merchants that use Forte's services. For questions or more information on these options, consult your Account Manager.

REST API Integration Overview

With the REST API integration option, partners can use their own online form templates and the parameters of Forte's REST API to securely capture merchant information. Submitting merchant data this way provides both you and the merchant an almost immediate application response and expedites the merchant onboarding process.

If you prefer to do your own underwriting or you already have a process in place for vetting merchants, you can integrate to Forte’s Direct-to-Enrollment solution. This process captures the merchant’s data using your branded application template and automatically approves and transfers the data to our Enrollment Team for onboarding.

Getting Started with REST

Before you can begin accepting applications, you'll need to create your API credentials and Authentication Headers and send a few test calls to make sure your form template is capturing the required parameters of the applications object. Before you begin, we recommend downloading Postman. Postman is a free, intuitive API development tool you can use to test Forte's REST API. We've created a collection of all the request calls detailed in Forte's REST API specification, which you can easily import into your Postman app for testing.

Step 1: Create Your API Credentials

To begin integration with Forte's REST API, you first have to create your API authentication credentials. These include an Access ID, which acts as your username, and an Secure Key, which acts as a password. We'll use these values to create your encoded Authorization header, which is required for every request you make via our API. Complete the following steps to create your API credentials:

Log into your Dex account.
Navigate to Developer > API Credentials. The API Credentials Datagrid displays. NOTE: If you do not see the Developer menu option, contact Forte Technical Support (888-235-4635 option 3) and request that they adjust your permissions so that you can create, update, and delete API credentials.
Click the Create button. The Create API Credentials Screen displays.
Enter a name for this API credential set in the Name field. For our purposes, we'll name our credential set Applications.
Click the Create New API Key button. Dex displays the Access ID and Secure Key values in their respective fields.
Use the Copy links to copy the Access ID and Secure Key values and store them in a secure location. NOTE: Once you copy and save your Secure Key value, you will not be able to see the value again. If you forget your Secure Key or it becomes compromised, you will have to regenerate the value in Dex.
Click the Back link to return to the API Credentials Datagrid. You should see your credentials displayed at the top of the list.
Repeat steps 3–7 to create additional credential sets.

Step 2: Get Your Fee ID

The fee_id parameter in the applications object identifies the rate plan that Forte created for you when you enrolled as a Partner. Rate plans correspond to the services or combination of services you want to offer to your merchants via the Forte platform. Rate plans can include pricing for the following combination of services:

eCheck Only
Credit Card Only
Gateway Only
Verification Only
eCheck + Credit Card
eCheck + Gateway
eCheck + Credit Card + Verification
Credit Card + Verification

You must include the fee_id parameter for every POST request made to the applications endpoint. Different rate plans correspond to different pricing arrangements and underwriting requirements for each merchant that applies. You should have receive your rate plan fee_id values from your Forte Account Manager; however, you can also look up the rate plans in Dex to ensure your merchant application template is referencing the correct fee_id.

To look up your rate plans, access your home organization and complete the following steps:

Navigate to the Rate Plans Datagrid (Merchant Application > Rate Plans). Search for the rate plan by Name or Fee ID and/or use the Status, Services, and/or Sales Rep filters to find the desired rate plan. The Rate Plans Datagrid displays the fee_id value in the ID column.
To view the details of a rate plan and ensure the pricing and Merchant Services Agreement(s) are correct, click the row on which the rate plan is displayed on the Rate Plans Datagrid. That Rate Plan’s Details Screen displays. From this screen you can view the detailed pricing configured for this rate plan, track which of your merchants have completed their applications, and monitor the progress of each submitted application. You can also confirm the fee_id value, which displays in the “General Information” card on the Rate Plan’s Detail Screen.

Step 3: Create Your Authentication Headers

At a minimum, requests to Forte's REST API must be authenticated using the Authorization header field and the custom header property, X-Forte-Auth-Organization-Id.

The Authorization Header

Forte’s REST web services rely on Basic access authentication over HTTPS using the API Access ID and an API Secure Key as the username and password values. These unique values are combined with a colon and then encoded using the RFC2045-MIME variant of Base64. The encoded string is then added to the HTTP Authorization header. For example, given that we created the following credentials set in Step 1,

API Access ID = 315c7649520edde96c5cbad59a5b265f
API Secure Key = c233f2958bd855d09d98397e74950640

the Authorization header we would submit with each API request would look like the following:

Authorization=Basic MzE1Yzc2NDk1MjBlZGRlOTZjNWNiYWQ1OWE1YjI2NWY6YzIzM2YyOTU4YmQ4NTVkMDlkOTgzOTdlNzQ5NTA2NDA=

You can quickly generate this value in Postman by completing the following steps:

In a new tab, enter a test URI for the request.
We will use:

				
					https://sandbox.forte.net/api/v3/organizations/org_300005/locations/loc_155161/customers/cst_SoGUG6mcLUS1nVzYBIbk3g/transactions/.

Click the Authorization tab and select Basic Auth from the Type dropdown menu.

In the Username and Password field, enter the API Access ID and API Secure Key you created earlier in Dex. For our example, we’ll use the following values:
- API Access ID = 315c7649520edde96c5cbad59a5b265f
- API Secure Key = c233f2958bd855d09d98397e74950640
Click the Preview Request button.

Postman automatically creates the Authorization header and displays it on the Headers tab.

This method works great if you’re using Postman to test your calls; however, if you’d rather test using another program or method you can also add Base64 encoding to HMAC requests to automatically convert the API Access ID and API Secure Key values into an encoded ASCII string. To do so, use the following code:

				
					Convert.ToBase64String(Encoding.Default.GetBytes(APIAccessID + ":" + APISecureKey)).Trim()

If you’re including the authentication request directly into the URI, you must encode the plus sign character (+) using %2B; and the forward slash character (/) using %2F;.

The X-Forte-Auth-Organization-Id Header

The custom header property X-Forte-Auth-Organization-Id specifies at which organization Forte should authenticate the request. The value of this header is also known as the home_organization_id.

The Accept Header

Forte’s REST service supports Content Negotiation through the Accept header sent in the request call. The default value for Accept headers is application/json which returns JSON responses. However, you can also use application/xml which returns XML responses.

The Content-Type Header

The Content-Type header is only required for POST and PUT calls. Like the Accept header, the Content-Type header supports both application/json and application/xml. The default value for Content-Type headers is application/json.

Putting it All Together

In summary, you must include the following headers for every POST and PUT request call made to the Forte REST API. For GET and DELETE request calls, the Content-Type header is optional:

Content-Type – This header is only required for POST and PUT calls. This field defaults to application/json, but also supports application/xml.
Accept – Defaults to application/json, but also supports application/xml.
X-Forte-Auth-Organization-Id – A custom header property that specifies at which organization Forte should authenticate the request (i.e., the home_organization_id)
Authorization – The API Access ID and API Secure Key encoded using the RFC2045-MIME variant of Base64.

The following code sample displays these headers within a GET call to the applications resource in the Sandbox environment.

				
					curl -X GET
   --H "Authorization: Basic MzE1Yzc2NDk1MjBlZGRlOTZjNWNiYWQ1OWE1YjI2NWY6YzIzM2YyOTU4YmQ4NTVkMDlkOTgzOTdlNzQ5NTA2NDA="
   --H "X-Forte-Auth-Organization-Id: org_300005"
   --H "Accept: application/json"

"https://api.forte.net/v3/organizations/org_300005/applications/

The following figure shows what the Headers tab in Postman should display for every POST or PUT request you send (GET and DELETE requests do not require the Content-Type header). NOTE: Some request calls, like POSTs to the documents resource requires additional headers. See the full REST API v3 reference for more details.

Step 4: Craft your Calls

ID Formatting

All resources in Forte’s REST API require object prefixing to identify the specific resource and aid in troubleshooting in the event of errors. The resource ID is a combination of the object prefix with the unique ID number or token that Forte assigns to the resource when a user creates it. The following table displays the prefixing standards used by Forte for resources applicable to applications. For a full list of resource prefixing standards, see the full REST API v3 reference:

Object	Prefix	Example
applications	app_ + ID	app_258741
documents	doc_ + ID	doc_3131dddgwef0gpV2eYlo5
locations	loc_ + ID	loc_100000
organizations	org_ + ID	org_200000

Supported Actions

Currently, partners can only create and search for the applications resource using the following HTTP verbs:

Action	HTTP Method	Description
Create	POST	Creates the application and returns the 'application_id' parameter in the response message.
FIND	GET	Returns summary information for all the applications that match the provided query parameters. For example, performing a GET call with a date range parameter to the 'applications' endpoint returns all the applications submitted within that date range. To return comprehensive/detailed information on a specific application, provide the 'application_id' within the endpoint.

Base URI

When crafting a call, append the resource endpoint to the following base URIs for the specified environments:

URL	Environment
https://sandbox.forte.net/api/v3	Sandbox
https://api.forte.net/v3	Live

Endpoints

Use the following endpoint URLs in the specified environments to create or search for merchant applications. NOTE: The organization_id referneced in the URL must be the home_organization_id of the partner.

Action	HTTP Method	URL	Description
CREATE	POST	/organizations/org_{{organizationID}}/applications	Creates the merchant application and routes the information to Forte's Underwriting and decisioning queues to return one of the following status codes: approved pending NOTE: POST requests in the Sandbox environment are not saved and the responses are generic.
FIND	GET	/organizations/org_{{organizationID}}/applications	NOTE: You can only test GET requests in the Live environment. Returns all applications submitted by the partner organization. To narrow down your search data using specific criteria, use the following filter parameters: start_updated_date / end_updated_date start_received_date / end_received_date status NOTE: All date filter parameters are time aware.
FIND	GET	/organizations/org_{{organizationID}}/ applications/app_{{applicationID}}	NOTE: You can only test GET requests in the Live environment. Returns a specific application submitted by the partner using the 'application_id' parameter.

General Request Filters

In addition to the filters listed above in the GET call that returns all applications submitted for an organization, you can also use the following general request filters to control the order and page size of your results set.

Parameter	Description
orderby	This filter sets the order of the results during a search request and uses the same fields accepted by the resource_filters. It can be followed by a space and one of the following values designating the order to use: asc - ascending value (default) desc - descending Example: https://api.forte.net/v3/organizations/org_300005/ applications?filter=start_received_date eq '2018-11-20' &orderby=start_received_date+desc&page_size=2&page_index=0
page_size	This filter sets the number of records returned on a page during a search request. It accepts values between 50 and 1000, but if you pass nothing, it defaults to 50. Example: https://api.forte.net/v3/organizations/org_300005/ applications?filter=status eq declined&orderby=received_date +desc&page_size=1000&page_index=3
page_index	This filter sets the index of the results page returned during a search request. The index starts at zero and has no upper limit; however, an index number set to a value higher than the maximum page size in a search request returns empty search results. Example: https://api.forte.net/v3/organizations/org_300005/ applications?filter=start_received_date+eq+'2018-01-01'+and +end_received_date+eq+'2018-06-30'&orderby=received_date+ desc&page_size=1000&page_index=5

The Applications Object

The applications object is where the magic happens. Use these parameters when building your template to capture your merchant’s data and automatically submit it to Forte’s Underwriting and decisioning queues (or Forte’s Enrollment team if you’re a Direct-to-Enrollment partner). If required, you can upload supporting documentation for applications using the documents object. The table below uses the following abbreviations and symbols to denote whether or not a parameter is required, optional, conditional, or return-only:

R = Required parameter for all applications
O = Optional parameter
C = Conditional parameter for applications with specific ownership percentages and/or legal structures. See the notes within the table.
— = A return-only parameter that does not need to be included in the request.

Parameter	Type	Length	Req	Description
fee_id	string	6	R	The ID of the rate plan, which details the fee values that Forte will charge the merchant. You can obtain the ID of your rate plan from your Forte Account Manager, or, if you have the permissions, from the Merchant Application > Rate Plans page in Dex.
source_ip	string	80	R	The IP Address from which the merchant is applying.
annual_volume	double	10	R	The anticipated annual volume of the business.
average_transaction_amount	double	5	R	The average transaction amount of the business. NOTE: When testing in the Sandbox environment, use this parameter to test success and fail responses. Passing a value greater than 10,000 in this field will trigger an automatic decline in Sandbox.
market_type	string	13	R	The method by which the business captures the majority of its transactions. Options for this parameter include the following values: internet phone mail point_of_sale
t_and_c_version	string	4	R	The version of Forte's Terms and Conditions provided to the applying merchant.
t_and_c_time_stamp	datetime	20	R	The date and/or timestamp when the merchant agreed to Forte's Terms and Conditions. NOTE: The value of this field can be up to one full day in the future. The following formats are supported: YYYY/MM/DD, MM/DD/YYYY YYYY-MM-DDTHH:MM:SSZ, YYYYMM-DDTHH:MM:SS
risk_session_id	string	128	R	A random unique code that partners generate on their client form and include in the API request call prior to sending the application Example: s%3AH5fDIdXjI7y1disbZChw8 Qrgl6Bz7uKZ.LjRrgNhYmuWApi%2F hdhB5wW4MgqknPHx1WR7s4RX1vWs The value of the risk_session_id parameter can be up to 128 characters (i.e., 128 bytes) long and can only consist of the following characters: Upper and lowercase English letters (a–z or A–Z) Digits (0–9) Underscore or hyphen (_ or -) See the following sections for information on how to generate a value for this parameter.
maximum_transaction_amount	double	10	O	The maximum allowable amount for a credit card or ACH transaction.
average_payable_amount	double	10	O	The average amount the merchant disburses in credit transactions (e.g., refunds, payroll, commissions, etc). NOTE: If either the average_payable_amount, maximum_payable_amount, or the monthly_payable_volume parameters are passed, all three parameters become required.
maximum_payable_amount	double	10	O	The maximum amount the merchant would disburse in a credit transaction (e.g., refunds, payroll, commissions, etc.). NOTE: If either the average_payable_amount, maximum_payable_amount, or the monthly_payable_volume parameters are passed, all three parameters become required.
monthly_payable_volume	double	10	O	An estimate of the amount the merchant disburses in credit transactions each month (e.g., refunds, payroll, commissions, etc). NOTE: If either the average_payable_amount, maximum_payable_amount, or the monthly_payable_volume parameters are passed, all three parameters become required.
received_date	datetime	-	-	The date and time when the application was received.
updated_date	datetime	-	-	The date and time when the application was updated.
sales_rep	string	-	-	The name or ID of the sales representative associated with this application.
location_id	string	-	-	If applicable, the merchant's location ID that Forte created after enrolling the applicant.
status	string	-	-	The status of the application. This field is return only. Supported values include the following: approved pending
decline_reason	string	-	-	The reason for a declined status. This field is return only. Supported values include the following: identity type of business credit reputation
applicant_organization	object	-	-	The applicant_organization object.
applicant_organization.legal_name	string	50	R	The legal name of the business. The value of this parameter must match the customer's Tax ID Number.
applicant_organization.tax_id_number	string	30	R	The Tax ID Number of the business (e.g., TIN, EIN, SSN, etc.). The following formats are supported: SSN = XXXXXXXXX, XXX-XX-XXXX ITIN = 9XXXXXXXX, 9XX-XX-XXXX EIN = XXXXXXXXX, XX-XXXXXXX
applicant_organization.legal_structure	string	37	R	The ownership type of the business. Options for this parameter include the following values: c_corporation government limited_liability_corporation partnership_general_or_limited publicly_held_corporation s_corporation sole_proprietorship tax_exempt_or_non_profit_organization
applicant_organization.dba_name	string	50	R	The name of the business as it will appear on your customer's statements. The default value for this parameter is the DBA (Doing Business As) Name.
applicant_organization.organization_id	string	-	-	If applicable, the merchant organization ID that Forte created after enrolling the applicant.
applicant_organization.street_address1	string	50	R	The physical address of the business. This parameter cannot contain P.O. boxes, including paid mailbox services provided by companies like the UPS Store.
applicant_organization.locality	string	50	R	The city where the business is located.
applicant_organization.region	string	2	R	The state or province where the business is located.
applicant_organization.postal_code	string	15	R	The zip/postal code of the business. The following formats are supported: XXXXX XXXXX-XXXX
applicant_organization.customer_service_phone	string	12	R	The customer service phone number of the business.
applicant_organization.website	string	100	R	The website of the business. The value of this parameter must be in www.yourcompanysite.com format. The www prefix is required. Slashes and underscore punctuation are allowed in the URL.
applicant_organization.business_type	string	50	R	The type of business. See Forte's list of Business Classification Codes that we currently support. Forte cannot process payments for businesses on our Prohibited Merchant List as these types of business are either illegal or high risk.
applicant_organization.bank_account_type	string	8	R	The type of bank account. This bank account can only be a business checking or business savings account; it cannot be the applicant's personal checking or personal savings account. The following values are supported: checking saving If no value is passed, this parameter defaults to checking.
applicant_organization.bank_routing_number	string	9	R	The routing number (i.e., TRN) of the applicant's bank. The value of this parameter must be nine digits. For Canadian merchants, this parameter must adhere to Forte's Canadian Routing Number formatting guidelines.
applicant_organization.bank_account_number	string	17	R	The account number (i.e., DDA) of the applicant's business bank account. The value of this parameter can only contain digits.
owner	object	-	R	The primary owner object. This owner must be the controller of the business.
owner.percentage	double	3	R	Indicates the percentage of the business owned by the primary owner (i.e., maximum ownership percentage = 100). NOTE: The sum of owner.percentage , owner_2.percentage, owner_3.percentage, and owner_4.percentage cannot be greater than 100. This field is NOT required for the following legal structures: government sole_proprietorship publicly_held_corporation
owner.title	string	-	O	The primary owner's official title at the company. Supported values include the following: ceo cfo coo managing_member general_partner president vice_president treasurer other
owner.first_name	string	50	R	The first name of the account owner.
owner.last_name	string	50	R	The last name of the account owner.
owner.street_address1	string	50	R	The home address of the account owner.
owner.locality	string	50	R	The city of the account owner's home address.
owner.region	string	2	R	The state or province of the account owner's home address.
owner.postal_code	string	15	R	The zip/postal code of the account owner's home address.
owner.country	string	3	R	The zip/postal code of the account own The ISO ALPHA-3 code of the account owner's home address (e.g., USA, CAN, etc.). NOTE: This field is NOT required for the following legal structures: government sole_proprietorship publicly_held_corporation
owner.citizenship	string	3	R	The ISO ALPHA-3 code of the account owner's country of citizenship (e.g., USA, CAN, etc.). NOTE: This field is NOT required for the following legal structures: government sole_proprietorship publicly_held_corporation
owner.email_address	string	100	R	The business email of the account owner. This email address cannot be a generic email address or a distribution list. The value of this parameter must be in a valid email format (e.g., john.doe@email.com).
owner.mobile_phone	string	15	R	The cell phone number of the account owner. The value of this parameter can be up to 15 characters (with country code).
owner.last4_ssn	string	4	R	The last four digits of the account owner's Social Security Number (SSN).
owner.date_of_birth	date	10	R	The birth date of the account owner in YYYY/MM/DD format.
owner_2	object	-	C	The secondary owner object. NOTE: This object is only required for American merchants with additional owner(s) who own at least a 25% share of the business.
owner_2.percentage	double	2	C	Indicates the percentage of the business owned by the secondary owner. This value must be 25 or greater. NOTE: This field is NOT required for the following legal structures: government sole_proprietorship publicly_held_corporation
owner_2.first_name	string	50	C	The first name of the account owner.
owner_2.last_name	string	50	C	The last name of the account owner.
owner_2.street_address1	string	50	C	The first name of the account owner.
owner_2.first_name	string	50	C	The home address of the account owner.
owner_2.locality	string	50	C	The city of the account owner's home address.
owner_2.region	string	2	C	The state or province of the account owner's home address.
owner_2.percentage	double	2	C	Indicates the percentage of the business owned by the secondary owner. This value must be 25 or greater. NOTE: This field is NOT required for the following legal structures:
owner_2.postal_code	string	15	C	The zip/postal code of the account owner's home address.
owner_2.country	string	3	C	The ISO ALPHA-3 code of the account owner's home address (e.g., USA, CAN, etc.). NOTE: This field is NOT required for the following legal structures: government sole_proprietorship publicly_held_corporation
owner_2.citizenship	string	3	C	The ISO ALPHA-3 code of the account owner's home address (e.g., USA, CAN, etc.). NOTE: This field is NOT required for the following legal structures: government sole_proprietorship publicly_held_corporation
owner_2.email_address	string	100	C	The business email of the account owner. This email address cannot be a generic email address or a distribution list. The value of this parameter must be in a valid email format (e.g., john.doe@email.com).
owner_2.mobile_phone	string	15	C	The business email of the account owner. This email address cannot be a generic email address or a distribution list. The value of this parameter must be in a valid email format (e.g., john.doe@email.com).
owner_2.email_address	string	100	C	The cell phone number of the account owner. The value of this parameter can be up to 15 characters (with country code).
owner_2.last4_ssn	string	4	C	The last four digits of the account owner's Social Security Number (SSN).
owner_2.date_of_birth	date	10	C	The birth date of the account owner in YYYY/MM/DD format.
owner_3	object	-	C	The tertiary owner object. NOTE: This object is only required for American merchants with additional owner(s) who own at least a 25% share of the business.
owner_3.percentage	double	2	C	Indicates the percentage of the business owned by the tertiary owner. This value must be 25 or greater. NOTE: This field is NOT required for the following legal structures: government sole_proprietorship publicly_held_corporation
owner_3.first_name	string	50	C	The first name of the account owner.
owner_3.last_name	string	50	C	The last name of the account owner.
owner_3.street_address1	string	50	C	The home address of the account owner.
owner_3.locality	string	50	C	The city of the account owner's home address.
owner_3.region	string	2	C	The state or province of the account owner's home address.
owner_3.postal_code	string	15	C	The zip/postal code of the account owner's home address.
owner_3.country	string	3	C	The ISO ALPHA-3 code of the account owner's home address (e.g., USA, CAN, etc.). NOTE: This field is NOT required for the following legal structures: government sole_proprietorship publicly_held_corporation
owner_3.citizenship	string	3	C	The ISO ALPHA-3 code of the account owner's home address (e.g., USA, CAN, etc.). NOTE: This field is NOT required for the following legal structures: government sole_proprietorship publicly_held_corporation
owner_3.email_address	string	100	C	The business email of the account owner. This email address cannot be a generic email address or a distribution list. The value of this parameter must be in a valid email format (e.g., john.doe@email.com).
owner_3.mobile_phone	string	15	C	The cell phone number of the account owner. The value of this parameter can be up to 15 characters (with country code).
owner_3.last4_ssn	string	4	C	The last four digits of the account owner's Social Security Number (SSN).
owner_3.date_of_birth	date	10	C	The birth date of the account owner in YYYY/MM/DD format.
owner_4	object	-	C	The quaternary owner object. NOTE: This object is only required for American merchants with additional owner(s) who own at least a 25% share of the business.
owner_4.percentage	double	2	C	Indicates the percentage of the business owned by the quaternary owner. This value must be 25 or greater. NOTE: This field is NOT required for the following legal structures: government sole_proprietorship publicly_held_corporation
owner_4.first_name	string	50	C	The first name of the account owner.
owner_4.last_name	string	50	C	The last name of the account owner.
owner_4.street_address1	string	50	C	The home address of the account owner.
owner_4.locality	string	50	C	The city of the account owner's home address.
owner_4.region	string	2	C	The state or province of the account owner's home address.
owner_4.postal_code	string	15	C	The zip/postal code of the account owner's home address.
owner_4.country	string	3	C	The ISO ALPHA-3 code of the account owner's home address (e.g., USA, CAN, etc.). NOTE: This field is NOT required for the following legal structures: government sole_proprietorship publicly_held_corporation
owner_4.citizenship	string	3	C	The ISO ALPHA-3 code of the account owner's home address (e.g., USA, CAN, etc.). NOTE: This field is NOT required for the following legal structures: government sole_proprietorship publicly_held_corporation
owner_4.email_address	string	100	C	The business email of the account owner. This email address cannot be a generic email address or a distribution list. The value of this parameter must be in a valid email format (e.g., john.doe@email.com).
owner_4.mobile_phone	string	15	C	The cell phone number of the account owner. The value of this parameter can be up to 15 characters (with country code).
owner_4.last4_ssn	string	4	C	The last four digits of the account owner's Social Security Number (SSN).
owner_4.date_of_birth	string	10	C	The birth date of the account owner in YYYY/MM/DD format.

Generating the Risk Session ID

The risk_session_id parameter offers partners a method of device identification/profiling and malware detection for merchant applications. As part of Forte's underwriting services, this parameter helps to identify client devices that may have been used for fraud in the past or that have inconsistent characteristics—such as a US-based IP address with Russian language settings. This parameter is required for partners using Forte's underwriting services but optional for Direct-to-Enrollment partners.

The script that generates the value for the risk_session_id parameter must be embedded on the page where the merchant applicant will be for five or more seconds. Profiling can only properly occur when the session runs on the applicant's browser for a minimum of five seconds. Additionally, the applicant's browser or the front-end software you're using to collect merchant applications must have JavaScript enabled.

To add the risk_session_id parameter to the applications object, complete the following steps:

Generate a unique risk_session_id code that fulfills the formatting requirements described in the applications resource reference table above by using the following PHP code sample:

				
					<html><body>
<?php $a=uniqid();
echo $a;
?>

<noscript>
<iframe style="width: 100px; height: 100px; border: 0;position: absolute; top: -5000px;" src="https://img3.forte.net/tags?org_id=xdzpgyj7&session_id=<?php echo $a;?>&pageid=1">
</iframe>
</noscript>
<script src="https://developers.forte.net/wp-content/cache/min/1/215e425e35e3a32d36ad7c56f1f2b71c.js" data-minify="1"></script><noscript><link data-minify="1" rel='stylesheet' id='genesis-blocks-style-css-css' href='https://developers.forte.net/wp-content/cache/min/1/wp-content/plugins/genesis-page-builder/vendor/genesis/blocks/dist/style-blocks.build.css?ver=1742279434' type='text/css' media='all' /><link data-minify="1" rel='stylesheet' id='genesis-page-builder-frontend-styles-css' href='https://developers.forte.net/wp-content/cache/min/1/wp-content/plugins/genesis-page-builder/build/style-blocks.css?ver=1742279434' type='text/css' media='all' /><link data-minify="1" rel='stylesheet' id='searchandfilter-css' href='https://developers.forte.net/wp-content/cache/min/1/wp-content/plugins/search-filter/style.css?ver=1747322229' type='text/css' media='all' /><link rel='stylesheet' id='elementor-frontend-css' href='https://developers.forte.net/wp-content/plugins/elementor/assets/css/frontend.min.css?ver=3.29.2' type='text/css' media='all' /><link rel='stylesheet' id='widget-image-css' href='https://developers.forte.net/wp-content/plugins/elementor/assets/css/widget-image.min.css?ver=3.29.2' type='text/css' media='all' /><link rel='stylesheet' id='e-sticky-css' href='https://developers.forte.net/wp-content/plugins/elementor-pro/assets/css/modules/sticky.min.css?ver=3.27.5' type='text/css' media='all' /><link rel='stylesheet' id='widget-heading-css' href='https://developers.forte.net/wp-content/plugins/elementor/assets/css/widget-heading.min.css?ver=3.29.2' type='text/css' media='all' /><link rel='stylesheet' id='widget-spacer-css' href='https://developers.forte.net/wp-content/plugins/elementor/assets/css/widget-spacer.min.css?ver=3.29.2' type='text/css' media='all' /><link rel='stylesheet' id='widget-icon-list-css' href='https://developers.forte.net/wp-content/plugins/elementor/assets/css/widget-icon-list.min.css?ver=3.29.2' type='text/css' media='all' /><link rel='stylesheet' id='e-animation-fadeIn-css' href='https://developers.forte.net/wp-content/plugins/elementor/assets/lib/animations/styles/fadeIn.min.css?ver=3.29.2' type='text/css' media='all' /><link rel='stylesheet' id='e-animation-fadeInLeft-css' href='https://developers.forte.net/wp-content/plugins/elementor/assets/lib/animations/styles/fadeInLeft.min.css?ver=3.29.2' type='text/css' media='all' /><link rel='stylesheet' id='widget-divider-css' href='https://developers.forte.net/wp-content/plugins/elementor/assets/css/widget-divider.min.css?ver=3.29.2' type='text/css' media='all' /><link rel='stylesheet' id='widget-form-css' href='https://developers.forte.net/wp-content/plugins/elementor-pro/assets/css/widget-form.min.css?ver=3.27.5' type='text/css' media='all' /><link rel='stylesheet' id='widget-social-icons-css' href='https://developers.forte.net/wp-content/plugins/elementor/assets/css/widget-social-icons.min.css?ver=3.29.2' type='text/css' media='all' /><link rel='stylesheet' id='e-apple-webkit-css' href='https://developers.forte.net/wp-content/plugins/elementor/assets/css/conditionals/apple-webkit.min.css?ver=3.29.2' type='text/css' media='all' /><link rel='stylesheet' id='widget-icon-box-css' href='https://developers.forte.net/wp-content/plugins/elementor/assets/css/widget-icon-box.min.css?ver=3.29.2' type='text/css' media='all' /><link rel='stylesheet' id='widget-nav-menu-css' href='https://developers.forte.net/wp-content/plugins/elementor-pro/assets/css/widget-nav-menu.min.css?ver=3.27.5' type='text/css' media='all' /><link rel='stylesheet' id='e-popup-css' href='https://developers.forte.net/wp-content/plugins/elementor-pro/assets/css/conditionals/popup.min.css?ver=3.27.5' type='text/css' media='all' /><link rel='stylesheet' id='widget-call-to-action-css' href='https://developers.forte.net/wp-content/plugins/elementor-pro/assets/css/widget-call-to-action.min.css?ver=3.27.5' type='text/css' media='all' /><link rel='stylesheet' id='e-transitions-css' href='https://developers.forte.net/wp-content/plugins/elementor-pro/assets/css/conditionals/transitions.min.css?ver=3.27.5' type='text/css' media='all' /><link rel='stylesheet' id='elementor-post-5-css' href='https://developers.forte.net/wp-content/uploads/elementor/css/post-5.css?ver=1750106773' type='text/css' media='all' /><link data-minify="1" rel='stylesheet' id='elementor-icons-theme-icons-css' href='https://developers.forte.net/wp-content/cache/min/1/wp-content/uploads/elementor/custom-icons/theme-icons/style.css?ver=1742279434' type='text/css' media='all' /><link data-minify="1" rel='stylesheet' id='font-awesome-5-all-css' href='https://developers.forte.net/wp-content/cache/min/1/wp-content/plugins/elementor/assets/lib/font-awesome/css/all.min.css?ver=1742279434' type='text/css' media='all' /><link rel='stylesheet' id='font-awesome-4-shim-css' href='https://developers.forte.net/wp-content/plugins/elementor/assets/lib/font-awesome/css/v4-shims.min.css?ver=3.29.2' type='text/css' media='all' /><link rel='stylesheet' id='widget-code-highlight-css' href='https://developers.forte.net/wp-content/plugins/elementor-pro/assets/css/widget-code-highlight.min.css?ver=3.27.5' type='text/css' media='all' /><link rel='stylesheet' id='widget-table-of-contents-css' href='https://developers.forte.net/wp-content/plugins/elementor-pro/assets/css/widget-table-of-contents.min.css?ver=3.27.5' type='text/css' media='all' /><link rel='stylesheet' id='elementor-post-989970-css' href='https://developers.forte.net/wp-content/uploads/elementor/css/post-989970.css?ver=1750641336' type='text/css' media='all' /><link rel='stylesheet' id='elementor-post-171-css' href='https://developers.forte.net/wp-content/uploads/elementor/css/post-171.css?ver=1750106774' type='text/css' media='all' /><link rel='stylesheet' id='elementor-post-1273-css' href='https://developers.forte.net/wp-content/uploads/elementor/css/post-1273.css?ver=1750106775' type='text/css' media='all' /><link rel='stylesheet' id='elementor-post-987754-css' href='https://developers.forte.net/wp-content/uploads/elementor/css/post-987754.css?ver=1750106775' type='text/css' media='all' /><link rel='stylesheet' id='elementor-post-1607-css' href='https://developers.forte.net/wp-content/uploads/elementor/css/post-1607.css?ver=1750106775' type='text/css' media='all' /><link rel='stylesheet' id='elementor-post-1450-css' href='https://developers.forte.net/wp-content/uploads/elementor/css/post-1450.css?ver=1750106775' type='text/css' media='all' /><link data-minify="1" rel='stylesheet' id='ekit-widget-styles-css' href='https://developers.forte.net/wp-content/cache/background-css/1/developers.forte.net/wp-content/cache/min/1/wp-content/plugins/elementskit-lite/widgets/init/assets/css/widget-styles.css?ver=1742279434&wpr_t=1753591016' type='text/css' media='all' /><link data-minify="1" rel='stylesheet' id='ekit-widget-styles-pro-css' href='https://developers.forte.net/wp-content/cache/min/1/wp-content/plugins/elementskit/widgets/init/assets/css/widget-styles-pro.css?ver=1742279434' type='text/css' media='all' /><link data-minify="1" rel='stylesheet' id='ekit-responsive-css' href='https://developers.forte.net/wp-content/cache/min/1/wp-content/plugins/elementskit-lite/widgets/init/assets/css/responsive.css?ver=1742279434' type='text/css' media='all' /><link data-minify="1" rel='stylesheet' id='vamtam-front-all-css' href='https://developers.forte.net/wp-content/cache/min/1/wp-content/themes/tecnologia/vamtam/assets/css/dist/elementor/elementor-all.css?ver=1742279434' type='text/css' media='all' /><link rel='stylesheet' id='vamtam-theme-elementor-max-css' href='https://developers.forte.net/wp-content/themes/tecnologia/vamtam/assets/css/dist/elementor/responsive/elementor-max.css?ver=1691310415' type='text/css' media='(min-width: 1025px)' /><link rel='stylesheet' id='vamtam-theme-elementor-below-max-css' href='https://developers.forte.net/wp-content/themes/tecnologia/vamtam/assets/css/dist/elementor/responsive/elementor-below-max.css?ver=1691310415' type='text/css' media='(max-width: 1024px)' /><link rel='stylesheet' id='vamtam-theme-elementor-small-css' href='https://developers.forte.net/wp-content/themes/tecnologia/vamtam/assets/css/dist/elementor/responsive/elementor-small.css?ver=1691310415' type='text/css' media='(max-width: 767px)' /><link data-minify="1" rel='stylesheet' id='elementor-gf-local-intertight-css' href='https://developers.forte.net/wp-content/cache/min/1/wp-content/uploads/elementor/google-fonts/css/intertight.css?ver=1742279434' type='text/css' media='all' /><link data-minify="1" rel='stylesheet' id='elementor-gf-local-inter-css' href='https://developers.forte.net/wp-content/cache/min/1/wp-content/uploads/elementor/google-fonts/css/inter.css?ver=1742279434' type='text/css' media='all' /><link data-minify="1" rel='stylesheet' id='elementor-gf-local-playfairdisplay-css' href='https://developers.forte.net/wp-content/cache/min/1/wp-content/uploads/elementor/google-fonts/css/playfairdisplay.css?ver=1742279434' type='text/css' media='all' /><link data-minify="1" rel='stylesheet' id='elementor-icons-ekiticons-css' href='https://developers.forte.net/wp-content/cache/min/1/wp-content/plugins/elementskit-lite/modules/elementskit-icon-pack/assets/css/ekiticons.css?ver=1742279434' type='text/css' media='all' /><link rel='stylesheet' id='elementor-post-987699-css' href='https://developers.forte.net/wp-content/uploads/elementor/css/post-987699.css?ver=1750106775' type='text/css' media='all' /><link rel='stylesheet' id='widget-nested-tabs-css' href='https://developers.forte.net/wp-content/plugins/elementor/assets/css/widget-nested-tabs.min.css?ver=3.29.2' type='text/css' media='all' /><link rel='stylesheet' id='elementor-post-987895-css' href='https://developers.forte.net/wp-content/uploads/elementor/css/post-987895.css?ver=1750106776' type='text/css' media='all' /><link rel='stylesheet' id='elementor-post-987741-css' href='https://developers.forte.net/wp-content/uploads/elementor/css/post-987741.css?ver=1750106776' type='text/css' media='all' /><link rel='stylesheet' id='elementor-post-988466-css' href='https://developers.forte.net/wp-content/uploads/elementor/css/post-988466.css?ver=1750106776' type='text/css' media='all' /><link rel='stylesheet' id='elementor-post-988556-css' href='https://developers.forte.net/wp-content/uploads/elementor/css/post-988556.css?ver=1750106776' type='text/css' media='all' /><link rel='stylesheet' id='elementor-post-988468-css' href='https://developers.forte.net/wp-content/uploads/elementor/css/post-988468.css?ver=1750106777' type='text/css' media='all' /><link rel='stylesheet' id='elementor-post-247-css' href='https://developers.forte.net/wp-content/uploads/elementor/css/post-247.css?ver=1750106777' type='text/css' media='all' /><link data-minify="1" rel='stylesheet' id='dashicons-css' href='https://developers.forte.net/wp-content/cache/min/1/wp-includes/css/dashicons.min.css?ver=1742279434' type='text/css' media='all' /><link data-minify="1" rel='stylesheet' id='wp-table-builder-css' href='https://developers.forte.net/wp-content/cache/min/1/wp-content/plugins/wp-table-builder/inc/frontend/css/wp-table-builder-frontend.css?ver=1742279434' type='text/css' media='all' /><link data-minify="1" rel='stylesheet' id='wp-table-builder-pro-css' href='https://developers.forte.net/wp-content/cache/min/1/wp-content/plugins/wp-table-builder-pro/inc/frontend/css/wp-table-builder-pro-frontend.css?ver=1742279434' type='text/css' media='all' /><link data-minify="1" rel='stylesheet' id='wp-table-builder-procommon-css' href='https://developers.forte.net/wp-content/cache/min/1/wp-content/plugins/wp-table-builder-pro/inc/common/css/wp-table-builder-pro.css?ver=1742279434' type='text/css' media='all' /><link rel='stylesheet' id='elementor-post-311-css' href='https://developers.forte.net/wp-content/uploads/elementor/css/post-311.css?ver=1750106777' type='text/css' media='all' /><link rel='stylesheet' id='widget-star-rating-css' href='https://developers.forte.net/wp-content/plugins/elementor/assets/css/widget-star-rating.min.css?ver=3.29.2' type='text/css' media='all' /><link data-minify="1" rel='stylesheet' id='elementskit-reset-button-for-pro-form-css-css' href='https://developers.forte.net/wp-content/cache/min/1/wp-content/plugins/elementskit/modules/pro-form-reset-button/assets/css/elementskit-reset-button.css?ver=1742279434' type='text/css' media='all' /><link data-minify="1" rel='stylesheet' id='elementor-gf-local-poppins-css' href='https://developers.forte.net/wp-content/cache/min/1/wp-content/uploads/elementor/google-fonts/css/poppins.css?ver=1742279434' type='text/css' media='all' /><link data-minify="1" rel='stylesheet' id='elementor-gf-local-lato-css' href='https://developers.forte.net/wp-content/cache/min/1/wp-content/uploads/elementor/google-fonts/css/lato.css?ver=1742279434' type='text/css' media='all' /></noscript></body>
</html>

Add the generated value to the following script (i.e., in place of UNIQUE_SESSION_ID). This script can be executed only once by the applicant’s browser.

				
					
<noscript>
<iframe style="width: 100px; height: 100px; border: 0;position: absolute; top: -5000px;" src="https://img3.forte.net/tags?org_id=xdzpgyj7&session_id=UNIQUE_SESSION_ID&pageid=1">
</iframe>
</noscript>

When generating the applications POST request, assign the unique code value created in step 1 to the risk_session_id parameter.
Submit the application.

Creating Applications - Code Sample

Example Request

				
					curl --request POST \
   --url 'https://api.forte.net/v3/organizations/org_300005/applications/' \
   --header 'Accept: application/json' \
   --header 'Authorization: {{Authorization}}' \
   --header 'Content-Type: application/json' |
   --header 'X-Forte-Auth-Organization-Id: org_300005' \
   --data '{
        "fee_id": 1648,
        "source_ip":"55.5.55.555",
        "annual_volume":"100000", 
        "average_transaction_amount": "10000",
        "maximum_transaction_amount":"5000",
        "average_payable_amount":"2500",
        "maximum_payable_amount":"10000",
        "monthly_payable_volume":"1000",
        "market_type":"internet",
        "t_and_c_version" : "Tc1",
        "t_and_c_time_stamp": "4/3/2016",
        "risk_session_id":"s%3AH5fDIdXjI7y1disbZChw8Qrgl6Bz7uKZ.LjRrgNhYmuWApi%2FhdhB5wW4MgqknPHx1WR7s4RX1vWs",
        "applicant_organization": {
           "legal_name":"George McFly Enterprises",
           "tax_id_number":"123456789",
           "legal_structure":"sole_proprietorship",
           "dba_name":"GMF Enterprises",
           "street_address1":"503 DeLorean Way",
           "locality":"Hill Valley",
           "region":"CA",
           "postal_code":"95420-4344",
           "customer_service_phone":"5555236987",
           "website":"www.GMFEnterprises.com",
           "business_type":"A10100",
           "bank_routing_number":"211170101",
           "bank_account_number":"121245611",
           "bank_account_type":"checking"
        },
        "owner": {
           "first_name":"George",
           "last_name":"McFly",
           "street_address1":"49 Great Scott! Drive",
           "locality":"Hill Valley", 
           "region":"CA",
           "postal_code":"95420-4345",
           "country": "USA",
           "citizenship": "USA",
           "email_address":"george.mcfly@GMFEnterprises.com",
           "mobile_phone":"214-448-5393",
           "last4_ssn":"6789",
           "date_of_birth":"3/3/1938",
           "percentage":"40"
        },
        "owner_2": {
           "first_name":"Marty",
           "last_name":"McFly",
           "street_address1":"52 Great Scott! Drive",
           "locality":"Hill Valley", 
           "region":"CA",
           "postal_code":"95420-4345",
           "country": "USA",
           "citizenship": "USA",
           "email_address":"martin.mcfly@GMFEnterprises.com",
           "mobile_phone":"972-712-3019",
           "last4_ssn":"5896",
           "date_of_birth":"11/3/1969",
           "percentage":"30"
        },
        "owner_3": {
           "first_name":"Jennifer",
           "last_name":"McFly",
           "street_address1":"54 Great Scott! Drive",
           "locality":"Hill Valley", 
           "region":"CA",
           "postal_code":"95420-4345",
           "country": "USA",
           "citizenship": "USA",
           "email_address":"j.mcfly@GMFEnterprises.com",
           "mobile_phone":"469-222-0608",
           "last4_ssn":"4455",
           "date_of_birth":"8/31/1969",
           "percentage":"30"
        }
}   '

Example Response – 201 Created

				
					{
    "fee_id": "1648",
    "annual_volume": 100000,
    "average_transaction_amount": 10000,
    "maximum_transaction_amount": 5000,
    "monthly_payable_volume": 1000,
    "average_payable_amount": 2500,
    "maximum_payable_amount": 10000,
    "source_ip": "55.5.55.555",
    "t_and_c_version": "Tc1",
    "t_and_c_time_stamp": "2016-04-03T00:00:00",
    "market_type": "internet",
    "risk_session_id": "s%3AH5fDIdXjI7y1disbZChw8Qrgl6Bz7uKZ.LjRrgNhYmuWApi%2FhdhB5wW4MgqknPHx1WR7s4RX1vWs",
    "applicant_organization": {
       "dba_name": "GMF Enterprises",
       "legal_name": "George McFly Enterprises",
       "street_address1": "503 DeLorean Way",
       "locality": "Hill Valley",
       "region": "CA",
       "postal_code": "95420-4344",
       "country": "USA",
       "website": "www.GMFEnterprises.com",
       "customer_service_phone": "555-523-6987",
       "legal_structure": "sole_proprietorship",
       "business_type": "A10100",
       "bank_routing_number": "211170101",
       "bank_account_type": "checking"
    },
    "owner": {
       "first_name": "George",
       "last_name": "McFly",
       "last4_ssn": "6789",
       "date_of_birth": "1938-03-03T00:00:00",
       "email_address": "george.mcfly@GMFEnterprises.com",
       "mobile_phone": "214-448-5393",
       "street_address1": "49 Great Scott! Drive",
       "locality": "Hill Valley",
       "region": "CA",
       "postal_code": "95420-4345",
       "country": "USA",
       "citizenship": "USA",
       "percentage": 40
    },
    "owner_2": {
       "first_name": "Marty",
       "last_name": "McFly",
       "last4_ssn": "5896",
       "date_of_birth": "1969-11-03T00:00:00",
       "email_address": "martin.mcfly@GMFEnterprises.com",
       "mobile_phone": "972-712-3019",
       "street_address1": "52 Great Scott! Drive",
       "locality": "Hill Valley",
       "region": "CA",
       "postal_code": "95420-4345",
       "country": "USA",
       "citizenship": "USA",
       "percentage": 30
    },
    "owner_3": {
       "first_name": "Jennifer",
       "last_name": "McFly",
       "last4_ssn": "4455",
       "date_of_birth": "1969-08-31T00:00:00",
       "email_address": "j.mcfly@GMFEnterprises.com",
       "mobile_phone": "469-222-0608",
       "street_address1": "54 Great Scott! Drive",
       "locality": "Hill Valley",
       "region": "CA",
       "postal_code": "95420-4345",
       "country": "USA",
       "citizenship": "USA",
       "percentage": 30
    },
    "response": {
       "environment": "live",
       "response_desc": "Application submitted has been approved."
    }
}

Finding Applications - Code Sample

Example Request

				
					curl --request GET \
   --url 'https://api.forte.net/v3/organizations/org_300005/applications?filter=start_received_date+eq+%272017-01-01%27+and+end_received_date+eq+%272017-06-30%27' \
   --header 'Authorization: {{Authorization}}' \
   --header 'Accept: application/json' \
   --header 'X-Forte-Auth-Organization-Id: org_300005'

Example Response – 200 OK Created

				
					{
    "number_results": 2,
    "search_criteria": {
    "page_size": 50,
    "page_index": 0,
    "home_organization_id": "org_334316",
    "resource_specific": {
       "start_received_date": "2017-01-01T00:00:00",
       "end_received_date": "2017-06-30T00:00:00"
    }
  },
  "results": [
    {
       "application_id": "app_111234",
       "location_id": "loc_123000",
       "status": "declined",
       "decline_reason": "reputation",
       "fee_id": "8258",
       "source_ip": "55.5.55.555",
       "annual_volume": 100000,
       "average_transaction_amount": 10000,
       "average_payable_amount": 1000,
       "maximum_payable_amount": 6000,
       "monthly_payable_volume": 600,
       "market_type": "internet",
       "t_and_c_version": "Tc1",
       "t_and_c_time_stamp": "2/3/2017",
       "risk_session_id": "s%3AH5fDIdXjI7y1disbZChw8Qrgl6Bz7uKZ.LjRrgNhYmuWApi%2FhdhB5wW4MgqknPHx1WR7s4RX1vWs",
       "applicant_organization": {
          "organization_id": "org_123456",
          "legal_name": "Biff Tannen Innovations",
          "legal_structure": "sole_proprietorship",
          "dba_name": "BTI",
          "street_address1": "503 DeLorean Way",
          "locality": "Hill Valley",
          "region": "CA",
          "postal_code": "95420-4344",
          "customer_service_phone": "5555236987",
          "website": "www.BTInnovations.com",
          "business_type": "A10100",
          "bank_routing_number": "211170101",
          "bank_account_type": "checking"
       },
       "received_date": "2017-02-03T09:22:34.63",
       "updated_date:": "2017-02-05T03:14:43.72",
       "sales_rep": "JohnnyBGoode",
       "fee_plan": "gold",
       "owner": {
          "first_name": "Biff",
          "last_name": "Tannen",
          "street_address1": "49 Great Scott! Drive",
          "locality": "Hill Valley",
          "region": "CA",
          "postal_code": "95420-4345",
          "country": "USA",
          "citizenship": "USA",
          "email_address": "b.tannen@BTInnovations.com",
          "mobile_phone": "5555698965",
          "date_of_birth": "3/3/1968",
          "percentage": 100
       },
       "links": {
          "documents": "https://api.forte.net/v3/applications/app_111234/documents",
          "self": "https://api.forte.net/v3/applications/app_111234"
       }
    },
    {
       "application_id": "app_998877",
       "location_id": "loc_456789",
       "status": "approved",
       "fee_id": "14081",
       "source_ip": "55.5.55.555",
       "annual_volume": 100000,
       "average_transaction_amount": 10000,
       "average_payable_amount": 2500,
       "maximum_payable_amount": 10000,
       "monthly_payable_volume": 1000,
       "market_type": "internet",
       "t_and_c_version": "Tc1",
       "t_and_c_time_stamp": "5/25/2017",
       "risk_session_id": "s%3AH5fDIdXjI7y1disbZChw8Qrgl6Bz7uKZ.LjRrgNhYmuWApi%2FhdhB5wW4MgqknPHx1WR7s4RX1vWs",
       "applicant_organization": {
          "organization_id": "org_987654",
          "legal_name": "George McFly Enterprises",
          "legal_structure": "sole_proprietorship",
          "dba_name": "GMF Enterprises",
          "street_address1": "503 DeLorean Way",
          "locality": "Hill Valley",
          "region": "CA",
          "postal_code": "95420-4344",
          "customer_service_phone": "5555236987",
          "website": "www.GMFEnterprises.com",
          "business_type": "A10100",
          "bank_routing_number": "211170101",
          "bank_account_type": "checking"
       },
       "received_date": "2017-05-25T05:29:48.62",
       "updated_date:": "2017-05-27T03:22:14.31",
       "sales_rep": "JohnnyBGoode",
       "fee_plan": "gold",
       "owner": {
          "first_name": "George",
          "last_name": "McFly",
          "street_address1": "49 Great Scott! Drive",
          "locality": "Hill Valley",
          "region": "CA",
          "postal_code": "95420-4345",
          "country": "USA",
          "citizenship": "USA",
          "email_address": "george.mcfly@GMFEnterprises.com",
          "mobile_phone": "5555698965",
          "date_of_birth": "3/3/1938",
          "percentage": 100
       },
       "links": {
          "documents": "https://api.forte.net/v3/applications/app_998877/documents",
          "self": "https://api.forte.net/v3/applications/app_998877"
       }
    }
  ],
  "response": {
     "environment": "live",
     "response_desc": "Get Successful."
  },
  "links": {
     "self": "https://api.forte.net/v3/applications/?filter=start_received_date+eq+%272017-01-01%27+and+end_received_date+eq+%272017-06-30%27"
  }
}

Finding a Specific Application - Code Sample

Example Request

				
					curl --request GET \
   --url 'https://api.forte.net/v3/organizations/org_300005/applications/app_109630' \
   --header 'Authorization: {{Authorization}}' \
   --header 'Accept: application/json' \
   --header 'X-Forte-Auth-Organization-Id: org_300005'

Example Response – 200 Created

				
					{
    "application_id": "app_109630",
    "organization_id": "org_234791",
    "status": "approved",
    "fee_id": "14081",
    "source_ip": "55.5.55.555",
    "annual_volume": 100000,
    "average_transaction_amount": 10000,
    "average_payable_amount": 2500,
    "maximum_payable_amount": 10000,
    "monthly_payable_volume": 1000,
    "market_type": "internet",
    "t_and_c_version": "Tc1",
    "t_and_c_time_stamp": "4/3/2016",
    "risk_session_id": "s%3AH5fDIdXjI7y1disbZChw8Qrgl6Bz7uKZ.LjRrgNhYmuWApi%2FhdhB5wW4MgqknPHx1WR7s4RX1vWs",
    "applicant_organization": {
       "organization_id": "org_852963",
       "legal_name": "George McFly Enterprises",
       "legal_structure": "sole_proprietorship",
       "dba_name": "GMF Enterprises",
       "street_address1": "503 DeLorean Way",
       "locality": "Hill Valley",
       "region": "CA",
       "postal_code": "95420-4344",
       "customer_service_phone": "5555236987",
       "website": "www.GMFEnterprises.com",
       "business_type": "A10100",
       "bank_routing_number": "211170101",
       "bank_account_type": "checking"
    },
    "received_date": "2017-05-25T05:29:48.62",
    "updated_date:": "2017-05-27T03:22:14.31",
    "sales_rep": "JohnnyBGoode",
    "fee_plan": "bronze",
    "owner": {
       "first_name": "George",
       "last_name": "McFly",
       "street_address1": "49 Great Scott! Drive",
       "locality": "Hill Valley",
       "region": "CA",
       "postal_code": "95420-4345",
       "country": "USA",
       "citizenship": "USA",
       "email_address": "george.mcfly@GMFEnterprises.com",
       "mobile_phone": "5555698965",
       "date_of_birth": "3/3/1938",
       "percentage": 100
    },
    "response": {
       "environment": "live",
       "response_desc": "Application submitted has been approved."
    },
    "links": {
       "documents": "https://api.forte.net/v3/applications/app_109630/documents",
       "self": "https://api.forte.net/v3/applications/app_109630"
    }
}

Step 5: Test Your Calls

Understanding Responses

Barring a formatting or authentication error, you should receive a response message for every request you send via the REST API. These responses echo back all the parameters you passed in the request with sensitive data such as account numbers and/or Social Security Numbers redacted to the last four digits. Optional request parameters whose values were null in the request do not echo back in responses. In addition to the echoed resource parameters, the response message also includes a response object.

For requests to the applications endpoint, only the following parameters display in the response object:

Parameter	Type	Description
environment	string	The environment in which you made the request. The value for this field can be either live or sandbox.
response_desc	string	A short description of the action's response.

Hypermedia

Forte’s REST API returns the following format for hypermedia responses. Result availability depends on the resource/action in the request. The following sample of hypermedia responses are merely formatting examples provided for reference.

				
					{
    "links": {
       "self":"https://api.forte.net/v3/applications?page_index=1",
       "prev":"https://api.forte.net/v3/applications?page_index=0",
       "next":"https://api.forte.net/v3/applications?page_index=2",
       "documents":"https://api.forte.net/v3/applications/app_998877/documents"
    }
}

Status Codes

Forte's web services use standard HTTP status codes along with messages where appropriate. The table below displays the most common codes:

Code	Text	Description
200	OK	This code indicates a successful HTTP request; the actual response depends on the request method. For example, responses for GET requests contain entities corresponding to the requested resource while responses for POST requests contain entities describing the result of the action.
201	Created	This code indicates that the server has fulfilled the request and has created a new resource.
400	Bad Request	This code indicates that the server cannot fulfill the request because of bad syntax (e.g., a request to create an application that does not include the required fee_id parameter).
401	Unauthorized	This code occurs when the user sends a bad username, password, and/or X-Forte-Auth-Organization-Id combination with the request.
404	Not Found	This code occurs when the user attempts an ID/token GET request, but the ID/token he/she provides does not exist in the database.
500	Internal Error	This generic error code indicates that the server has encountered an unexpected condition and cannot provide a more specific or suitable error message.

For status codes in the 400s, ensure that you correctly formatted the JSON (or XML) in the original request, especially when the system returns a descriptive error message along with the status code such as the following example messages:

				
					{
    message: "Authentication Organization ID in header is missing or invalid."
}

				
					{
    message: "Payment Method's routing number length is invalid."
}

Testing in Postman

To help you gain a greater understanding of how Forte’s REST API works, we’ve built a Postman collection of sample REST requests that you can use to test each resource, including applications.

Creating Environments

While we’ve included sample body parameters in this collection of request calls, you’ll still need to add the URL endpoints and Authentication Headers described in Step 3 above. The easiest way to start testing these sample request calls is to create your own environment that includes global variables. All of the calls to the applications resource in our collection include the following variables:

Variable	Example	Description
baseURL	https://sandbox.forte.net/api/v3 (Sandbox) https://api.forte.net/v3 (Live)	The base URI that all Forte REST calls use. When constructing a call, append the resource endpoint to the URI for the applicable environment.
organizationID	300005	The Organization ID without the resource prefix. Our collection includes the prefix for all resources—the only variable is the ID number. Your Account Manager will provide you with your Organization ID.
apiaccessid	315c7649520edde96c5cbad59a5b265f	The API Access ID value that you created in Step 1: Create Your API Credentials. This value is created and maintained in Dex.
apisecurekey	c233f2958bd855d09d98397e74950640	The API Secure Key value that you created in Step 1: Create Your API Credentials. This value is created and can be regenerated in Dex.

To create an environment for our Postman collection, complete the following steps:

Navigate to our REST API v3 Reference, and click . If the collection does not open in the native app, click either the Postman for Chrome or Postman for Windows option. The collection imports into Postman.

Click > Manage Environments in the upper-right corner of the screen.

The Manage Environments modal displays.

Click . The Add Environment fields display.

Give your environment a name in the Environment Name field. This name should be concise and indicate whether calls using this environment will be sent in Sandbox or Production.
Add the baseURI, organizationID, apiaccessid, and apisecurekey variables in the Key column and the values for these parameters in the Value column. A completed Add Environment modal looks similar to the following.

Click . The Manage Environments modal displays your newly created environment.

Repeat steps 3–6 to additional environments (e.g., Live).

Testing Your First Call

After creating your global variables in an environment, you're ready to run your first call. To do so, complete the following steps:

From the Forte REST API v3 collection menu, click Applications > POST Application. Postman loads the URL.

Click the dropdown menu in the Environment field and select the environment in which you want to send this request. Since we’re just testing POST requests, we’ll select “Sandbox” for the sake of this example. The variables in the URL should change from red to orange, indicating that Postman recognizes them as variables with a defined value.

Click the Headers tab and enter the Authorization, X-Forte-Auth-Organization-Id, Accept, and Content-Type headers in Key column and their values in the Value column. NOTE: To quickly add these headers to a call, create them in a .txt file and then copy and paste them using the Bulk Edit link on the Headers tab in Postman. Your headers tab should look similar to the following figure:

Click the Body tab. Ensure that the raw radio button is selected and the JSON (application/json) option displays. The POST and PUT requests in our REST collection include the required parameters for every resource; however, the applications resource includes body parameters that must be customized with your values for successful submission, specifically, the fee_id parameter and, depending on the environment, the risk_session_id parameter. You can obtain the value of the fee_id parameter by accessing the Rate Plans Datagrid in Dex (i.e., Merchant Applications > Rate Plans), or, if you don’t have permissions to access this menu option, from your Forte Account Manager.

After customizing the Header and Body tabs with your values, click . Barring any formatting errors in the request, Postman displays the response message from Forte and its status code.

If you’d like to save this call with your header and body parameters, click to add the call to your imported collection.

After creating a few test applications with varying scenarios and customer stories, you can test the GET calls using the same process you used when creating a POST (except for customizing the parameters of the Body tab). NOTE: Forte does not save the data for applications created in the Sandbox environment; therefore, when testing GET calls, you must use the Live environment. Once you’re comfortable with the parameters of the applications resource, you can begin building your merchant application template on your site.

Integrations

Peripherals

Merchant.docs

Partner.docs

Merchant.docs

Merchant.docs

Partner.docs

First Time Users

Quick Start

Transactional

Customer data

Tutorials

Response Code

Code samples

Third Party Modules

Plugins & More

Drivers

Additional Support

Applications - Partners

Overview

Using Forte's Underwriting Services

REST API Integration Overview

Getting Started with REST

Step 1: Create Your API Credentials

Step 2: Get Your Fee ID

Step 3: Create Your Authentication Headers

The Authorization Header

The X-Forte-Auth-Organization-Id Header

The Accept Header

The Content-Type Header

Putting it All Together

Step 4: Craft your Calls

ID Formatting

Supported Actions

Base URI

Endpoints

General Request Filters

The Applications Object

Generating the Risk Session ID

Creating Applications - Code Sample

Finding Applications - Code Sample

Finding a Specific Application - Code Sample

Step 5: Test Your Calls

Understanding Responses

Hypermedia

Status Codes

Testing in Postman

Testing Your First Call

On this page

Your benefits:

What happens next?

Get Connected to our Team

Simplifying IT for a complex world.

Platform partnerships

Services

Business Challenges

Digital Transformation

Security

Automation

Gaining Efficiency

Industry Focus

Simplifying IT
for a complex world.