Encompass APIs

Number of APIs: 2

📄 Get started here

Encompass does not have 'standard' API endpoints such as you might find in an Open API standard

Instead, each endpoint is designed for a specific integration to deliver or receive exactly the data needed by that integration.

The endpoints can be built on top of any core functionality, or you can build your own backend functionality with Cloud Functions. When creating your API Command in Encompass, you will select the 'Inherits API Command' to tell the system which core functionality it is extending (unless it is a Cloud Function).

For example, if you have built a Fusion report, and want to expose the data on your own API Command endpoint, you will add an API Command with Inherits API Command = FusionView, and set the API Parameters to make sure there is one for 'ReportID={your report id}'

Each API Command created in Encompass has a globally unique name, which is used to identify it when calling the URL.

Example: https://api.encompass8.com/api?APICommand=myTableViewTest&EncompassID=Pioneer&APIToken={Token}

Getting started guide

• You must use a valid API Token to send requests to the API endpoints. You can get your API Token from Encompass with an API Certification. See Authentication below
• All APIs have rate and usage limits, which you can configure on each API Command.
• All APIs are subject to $0.01 per processing second fees
• The APIs only respond to HTTPS-secured communications. Any requests sent via HTTP return an HTTP 301 redirect to the corresponding HTTPS resources.
• The APIs usually support returning data in any number of formats, by passing in the standard Format parameter. Example: Format=JSON . Available formats are: JSON, XML, CSV, HTML. Some APIs do not support all of the available supports in Encompass.
• If you are utilizing the generic 'api.encompass8.com' endpoint, you will be required to pass in the 'EncompassID' parameter to identify which system the API should run on. If you are utilizing a system-specific url (ex: pioneer.encompass8.com), then the EncompassID is not required.
• Encompass often utilizes redirects to get API calls routed to the correct version that each particular Encompass system is using. Ensure any code calling Encompass APIs is always following redirects.

Authentication

To get your Encompass API Token, you will need to have an Encompass API/Code Block Certification.

Encompass regularly hosts training for this certification program.

If you are an experienced developer and don't believe you need to go through the training to get access to an API Token, please contact Encompass and request to test out of the API Certification.

Once the certification is complete, you will be given your own Solution/Application/APIToken in the Encompass system.

You can then grant that API Token the permission codes it needs based on the activities in Encompass you would like to use it for.

• For example, if you plan to use the API Token to modify product information, it will need the 'ProductEdit' permission code.

You can also create multiple API Tokens, each with their own set of permission codes. And you can use the Active status on each API Token to rotate the tokens as needed.

Encompass API Tokens are 32 character random collections of letters, numbers, and symbols.

Do not share your API Token!

After an API Command is created, it must be installed on each system for it to be allowed to run on that system. This allows you to create an API Command, then utilize it against any Encompass system in the network, as long as the administrator of that system is willing to install the API.

• ie: 'Installing the API' just means granting access for it to be allow to run on this system

The API Commands are installed in the App Library in Encompass.

Authentication error response

If an API token is missing, malformed, or invalid, you will receive an HTTP 401 Unauthorized response code. Note: if the Always Return HTTP 200 setting is turned on for the API Command, then the HTTP code will still be 200 even though the response is an error. Turning this setting off will allow the server to return the actual 401 HTTP response code.

{
    "errors": [
        {
            "status": "401",
            "title": "Session or OAuthToken Expired",
            "detail": "URL does not include APIToken and User is not logged on.",
            "APICommand": "GetSettingsBySettingID"
        }
    ]
}

Rate and usage limits

All APIs are subject to $0.01 per processing-second fees.

The timer for the API processing begins as soon as the request is recieved by Encompass, and ends as soon as the final byte is transferred in the response.

• aka: The processing time includes data transfer time, which affects large data uploads/downloads

The following settings are available and configurable by the API creator to control their costs:

503 response

An HTTP 503 response from our servers indicates there is an unexpected spike in API access traffic. The server is usually operational within the next five minutes, please check the Encompass Status Page for updates. If the outage persists or you receive any other form of an HTTP 5XX error, contact support.

API Parameters

In Encompass, you are able to control exactly which API Parameters are allowed and now allowed on each API you create. You can also control the specific details of each parameter, such as the data type, maximum length, how it should be passed in, and even the format of the JSON document (if it is that data type).

This has 3 main benefits:

1. Strong typing: Encompass will enforce that the parameters that the API caller uses pass all of the settings on your API Parameters before passing them to the core code or Cloud Function. This reduces the amount of validation and error handling needed in the rest of the code
2. Security: Strong enforcement of exactly what is expected on API Commands reduces the likelyhood of a vunerability through a developer not realizing how one of the parameters could be used nefariously
3. Automatic documentation: Encompass utilizes these configured API Commands and API Parameters to automatically create documentation for all of the APIs in the system. To see the API documentation, go to the API Command Lookup in your Encompass system.

Cloud Functions

Cloud Functions allow for custom server side, Web API code to be built and executed on demand, hosted by Encompass.

Cloud Functions let you run code and take advantage of the existing Encompass API system,
all without provisioning or managing servers, dealing with permissions and versions, or worrying about up-time and maintenance.

Cloud Functions are:

• written directly in Encompass using a built in development environment
• have version control handled by Encompass and are backed up
• automatically deployed and maintained in the Encompass Cloud
• auto-scaling
• setup for high availability
• built with the Encompass SDK for faster coding and easy interaction with the Encompass system
• easily attached to Encompass Table Edit Triggers for custom Web Hooks
• written in C# (.Net 6)

For more information on Cloud Functions, see the full documentation in your Encompass system on the 'Cloud Functions' page (Dashboard ID 166849)

Diagram of standard external API request to Encompass

Diagram of a Table Trigger (web hook)

1. Sample Table View - mySampleTableView GET {{baseUrl}}?APICommand=mySampleTableView&EncompassID={{EncompassID}}

2. Sample Table Import - mySampleBrandUpdate POST {{baseUrl}}?APICommand=mySampleBrandUpdate&EncompassID={{EncompassID}}