Skip to main content
Mitratech Success Center

Client Support Center

Need help? Click a product group below to select your application and get access to knowledge articles, webinars, training content, and release notes or to contact our support team.

Authorized users - log in to create a ticket, view tickets status and check your success plan details.

 

External API

  1. Last updated
  2. Save as PDF
The External API tutorial will give you a brief insight into how one might set up an external API to hook into TAP. Learn the parameters that you will need to set up in order for information to be pushed or pulled to a 3rd party app.

 

What is the External API Property?

The External API property is a relationship level property that enables a workflow to send information to a particular location and in a particular way. By using the External API property, TAP can communicate with other applications and "do" certain things to them. To learn more about what an API is, click here.  

 

 

How do I set up an External API with TAP?

TAP has out-of-box Salesforce, Team Connect, and e-Signature integrations, which means that the API has already been set up and is within the infrastructure of TAP. If you want to integrate with another software that is not out of box, you can do that with an external API by following the instructions below.

  1. First, navigate to the workflow builder in the designer tool, and select the relationship at which you would like to communicate with another application.
  2.  After selecting the relevant relationship or stage, click on the clipboard_ebd65b17b8d54315f52d3c7dba25660a8.pngExternal API icon. A dialog box will appear.
     
  3. To create a call, click the 'Add' button in the bottom right hand corner.

External API Trigger.png

Each stage/relationship can have multiple API calls configured. At the stage level, calls will be triggered according to the parameters set within the configuration. At the relationship level, all calls will proceed in series once the stage has been submitted.

You can set up multiple calls at relationship level. For instance, one call to collect the API token and other to GET files or upload documents using POST method. All these calls will be displayed in the External API main screen as labels.

At the stage level there is a limit to add API calls which is dependent on the setting 'TriggerCountThreshold'.

Follow the steps listed in each section to correctly set up an external API.

Main Info
  1. In the Configuration Name box, type the API configuration name which will appear as label on the External API screen. 
  2. In the API URL box, type in the API end point. 
  3. In the Method drop down, select the type of API call you wish to make, whether a GET request, POST request, etc. 
  4. Select the checkbox for Prevent workflow submission if response is invalid if this fits in with your business needs. This setting ensures that a bad call prohibits further movement in the workflow. 
  5. Click the Add button to add headers, which provide metadata within the request. This is not required but it is encouraged.

 API Trigger Main Info.png 

Automatic Retries for API Call Failures

(v1.20 and above)

TAP automatically retries most outbound API calls upon encountering an error, improving the chances of a successful response in the event of transient issues. This applies to the Relationship Ext API, Stage Ext API, External Datasource, and the External Grid Datasource. 

A retry will be automatically triggered in the following cases:

  • 500 - Internal Server Error
  • 504 - Gateway Timeout
  • 503 - Service Unavailable
  • 408 - Request Timeout
  • Any exception encountered while calling the API endpoint
  • Transient errors
Request

For POST, PUT, DELETE, HEAD, OPTIONS, PATCH, and MERGE methods the request section becomes available.

 API Trigger Request.png

You can add form fields to the request by using the icon in the right hand corner (black rectangle with blue arrow). This icon will allow you to tag form result values into your request. It will also allow you to map documents into the request. These documents must be either associated with an eSign relationship, a doc builder/doc field document, or an upload field.

Response

The response is used when you need to return information to a TAP field. For example, if you have an authorization call and receive a token, you can return that token into a TAP field. Then, you can set up a second API call to push that information forward. 

  1. Select the text field into which you would like to parse your data. Use the ID of the response in the Use Formula Calculation.

 API Trigger Response.png

Aliases

When you get a response from an API it has it's own formatting. With the Aliases function, you can rename that response whatever is most helpful for you. 

Note: You only need to do aliases if you're going to refer to it in your responses. 

  1. The Alias key is the value you want to return.
  2. Body identifies where in the response you will display this value.
  3. Object navigation is the untouched response from the API call. 

 API Trigger Aliases.png

Validation

Validation allows you to set up custom error messages. 

  1. Add a custom message in the Custom error message box.
  2. Click the Add new condition rule to attach conditions to the error message or validation.

 API Trigger Validation.png

Authorization

Authorization allows you to set up authorizations. You may choose no auth, basic, Oath 2.0, or use existing from another relationship. Form field results may used to pull in values when using basic auth. 

When interacting with an external API from TAP, the authentication method is determined based on the external API's configuration.

  • If the API doesn't require authentication, the choice is 'No Auth.'
  • For APIs with username and password authentication, 'Basic Auth' is selected.
  • If OAuth 2.0 authentication is required, 'Use OAuth 2.0' is the appropriate option.
  • Choosing 'Use Existing' indicates the selection of a previously configured authentication in the workflow.

API Trigger Authorization.png 

Files

If part of your API response sends a file, setting up files allows you to return those files into your TAP form. 

 API Trigger Files.png

 

Click Save when finished. 

API Trigger Finish.png

Stage Level API Calls

The stage level external API must always be triggered by a form field, usually a button field. Users can configure a variety of call types that utilize a variety of different formatting. Up to 5 calls can be configured per stage, and these calls can be triggered in sequence, or separate of each other. 

NOTE: When a stage level call is linked to a field that is not a button field, the user must add a value to that field and then click out of the field in order to trigger the associated call. When a stage level call is linked to a button field, the user must simply click the button in order to trigger the associated call.

Use Cases

  • Sending information from TAP to a third party system.

  • Pulling in information from a third party system that is used to populate a form.

  • Initiating new TAP records as part of a workflow process. API calls can be setup within a workflow to use TAP's own endpoints and initiate a new workflow record as part of a step in the workflow process. The advantage of using this over the Child Workflow functionality is that workflows initiated through the API will have the first stage of the workflow submitted. When a workflow is initiated using Child Workflow functionality the first stage is created and assigned, but is not submitted.