Minimum Version Required: 22.07
Steps
Overview:
Unlike typical Open APIs, Encompass APIs are tailored to each integration, delivering only the necessary data. These endpoints can utilize Encompass's core features or be built with custom Cloud Functions.
To create an API Command in Encompass, select the 'Inherits API Command' to specify the core functionality it extends (unless it's a Cloud Function).
Example: To make a Fusion report available via an API, create an API Command with 'Inherits API Command = FusionView' and a 'ReportID={your Report ID}' API Parameter.
Encompass API Commands are identified by a unique name in the API URL.
This allows access to any data from any Encompass system through a REST URL.
API charges are based on processing time and the amount of data transferred.
Getting Started:
Authentication: All requests require a valid API Token. Get a token via Encompass API Certification (see "Authentication")
Rate/Usage: Be aware of configurable rate and usage limits. API costs $0.01 per processing second.
Security: Only HTTPS is supported. HTTP requests are redirected.
Data Format: Use the "Format" parameter to request data in different formats (e.g., Format=JSON). Options include JSON, XML, CSV, HTML (availability varies).
API Endpoint:
For the generic endpoint (api.encompass8.com), include the "EncompassID" parameter.
System-specific URLs (e.g., training.encompass8.com) don't need "EncompassID."
Redirects: Your code must handle Encompass API redirects.
Authentication:
Access to Encompass APIs is controlled through API Tokens, which are obtained by completing the Encompass API/Code Block Certification. Encompass provides regular certification training.
Successful completion grants API Edit permission within the Encompass system.
Upon successful completion API creators can ask for the APISoultionAdmin to access API Tokens. Encompass API Tokens consist of 32 random characters (letters, numbers, and symbols).
Security Warning: Do not share your API Token!
Before an API Command can be executed on an Encompass system, it must be "installed" (granted access) through the App Library.
Rate and Usage Limits:
Encompass API usage is subject to a processing fee of $0.01 per second.
NOTE: Processing Time is calculated from the moment Encompass receives the request until the complete response is sent. This includes the time it takes to transfer data, which can impact larger uploads and downloads.
To help manage costs, API creators can configure the following settings:
Timeout In Seconds: The maximum allowed processing time for a single API request (typical values: 5-30 seconds).
Processing Limit (Minutes per Hour): The maximum total processing time allowed for this API Command within a single hour across all Encompass systems. This limit resets hourly.
API Parameters:
Encompass provides granular control over API Parameters, allowing API creators to define which parameters are allowed or disallowed for each API. They can also configure parameter details, including:
Data type
Maximum length
How the parameter is passed
JSON document format (if applicable)
This offers three key benefits:
Strong Typing: Encompass enforces parameter settings, reducing validation and error handling in your code.
Security: Enforcing parameter expectations minimizes the risk of vulnerabilities arising from unexpected parameter usage.
Automatic Documentation: Encompass automatically generates API documentation from these parameter configurations. Access this documentation via the "API Command Lookup" in your Encompass system.
Understanding the API Endpoint:
All Encompass API calls use the /API endpoint. The desired operation is specified using parameters:
Example: API?APIToken={Your API Token}&EncompassID={Encompass System}&APICommand={API Command Name}
In this example:
APIToken: Your unique API security key.
EncompassID: The specific Encompass system to access.
APICommand: The name of the API function to execute (this acts like a specific endpoint).
This approach enables Encompass to handle various API requests through a single URL.
For details on API Certification pricing, please visit the Certification and Training Dashboard in Encompass
Fields And Definitions
API = Application Programming Interface
REST = Representational State Transfer
URL = Uniform Resource Locator
API Endpoint = In APIs, an endpoint is typically a uniform resource locator (URL) that provides the location of a resource on the server.