eCompliance API Help

The eCompliance API is a RESTful, HATEOAS enabled interface for accessing your eCMS data in JSON or XML format over HTTP. The API is intended to provide secure, predictable resource-based URLs making it simple to rapidly develop web and desktop applications that integrate with eCompliance.

The following documentation provides information for the latest version of the API. Read the contents of the page carefully to understand the general guidelines for making use of the API. If you do not currently have access to the API, or you have additional questions, please contact us at: support@ecompliance.com

eCompliance API Overview

To enable the API for your organization contact eCompliance support.

Authentication

All requests for user and organization data need to be authenticated using a token. The token can be obtained by either one of the two methods given below. Tokens do expire, after which time a new token must be requested, see "Authentication token expiration" below.

How to retrieve a token with a user name and password

URL	~/Token
Description	Returns a bearer token. This token is used for authentication and will expire.
Method	POST
Request Content Type	application/x-www-form-urlencoded; charset=utf-8
Request Body	userName={userName}& password={password}& grant_type=password
Return Data	{ "access_token": "{veryLongApiKey}", "token_type": "bearer", "expires_in": "{minutes}", "issued": "{date}", "expires": "{date}" }
Possible Status Codes	200, 400, 500

How to retrieve a token with a API Key

The API token can be obtained by logging into eCMS, going to the settings tab and copying your API key. The API key will only be available if the API has been enabled by eCompliance.

URL	~/Token
Description	Returns a bearer token. This token is used for authentication and will expire.
Method	POST
Request Content Type	application/x-www-form-urlencoded; charset=utf-8
Request Body	ApiKey={yourApiKey}& grant_type=password
Return Data	{ "access_token": "{veryLongApiKey}", "token_type": "bearer", "expires_in": "{minutes}", "issued": "{date}", "expires": "{date}" }
Possible Status Codes	200, 400, 500

Authentication token expiration

You can use the following information to determine when an authentication token has expired or is no longer valid.
When a token has expired, a new one must be requested. Follow the "Authentication" section above.

Message	The Authentication token has expired.
Possible Status Codes	401

Required Headers

All calls to the API require that the following HTTP headers are included. An error will be returned if one of these headers is missing.

Header Name	Header Value	Notes
authorization	"bearer {access_token}"	Required for all calls except Authentication.
x-version	"{versionNumber}"	Required for all calls. Current version is "1".
x-site	"{id}"	Required for all calls. This is often your Organization ID or Site ID if you're using a user with less permissions. Contact support@ecompliance.com if you need this information.

Encryption

The API requires that all communication takes place over HTTPS.

Versioning

The API uses versioning as a way to guarantee that our API contract doesn't change for developers unexpectedly. If a newer version of the API is released, previous versions will continue to function. When making a request to the API, you MUST specify the version you are expecting to use by specifying the version via HTTP header.

We occasionally release newer versions of the API. If this happens and you are registered to use the API, you’ll receive an email notifying you of the upcoming changes, and the documentation on this page will be updated accordingly.

Note that developer support is available only for the current version of the API, as well as the most recent previous version of the API.

Header Name	Header Value	Header Description
x-version	{versionNumber}	The version to use, "1", "2", etc. Not passing a version will return an error that includes the current version of the API.

Paging

Most of the eCMS API endpoints that return lists also provide paging capabilities.

Paging Limits

Default page size 10.
Maximum page size is 50.

Making a request with paging

When making a request for paged results, use query string parameters:

http://api.ecompliance.com/inspections?page=1&pageSize=15

A valid paged request will return a result similar to this:

{
	"pagingInfo": 
	{
		"pageNumber": 1,
		"pageCount": 1,
		"pageSize": 10,
		"totalNumberOfItems": 8
	},
	"values": [{},{}],
	"links": {}
}

Note: pagingInfo contains information regarding the amount of data. values is an array of data for the specific resource requested. links is a set of links to navigate the paged data (See HATEOAS)

Paging with HATEOAS The API also makes use of HATEOAS links for paging. In a nutshell, developers should try and use the links from the returned JSON results for subsequent requests instead of building their own paths by hand.
The results of a page will contain these links in an array called Links:

"links": 
[
    {
        "href": "http://localhost:14/api/inspections?page=3&pageSize=2",
        "rel": "nextPage",
        "method": "GET"
        },
        {
        "href": "http://localhost:14/api/inspections?page=1&pageSize=2",
        "rel": "previousPage",
        "method": "GET"
        },
        {
        "href": "http://localhost:14/api/inspections?page=1&pageSize=2",
        "rel": "firstPage",
        "method": "GET"
        },
        {
        "href": "http://localhost:14/api/inspections?page=4&pageSize=2",
        "rel": "lastPage",
        "method": "GET"
        }
    }
]

Filtering & Sorting

Most of the eCMS API endpoints that return lists also provide filtering and sorting capabilties. Check the desired endpoint from the endpoint listing below to determine what filtering and sorting parameters are available.

Errors

The API makes use of the standard set of HTTP response codes to indicate success/failure of requests. Where possible, errors will return information in the response about why the request failed.

Data Formats

JSON is the preferred data interchange format for the eCompliance API, and all requests will return JSON by default. XML is also supported, and the desired format can be specified by HTTP Header. Use the headers below to determine the response type.

Date formats: If numeric, they should follow the ISO-8601 format of: yyyy-mm-dd, such as 1989-05-22. Please check that your local system follows this format to prevent errors in date translation. Alternatively, mixed text format of: MMM-dd-yyyy (MAY-22-1989), is also accepted. These are the only 2 formats that will prevent confusion of month and day.

Response type	`Accept` header
JSON	`application/json`
XML	`application/xml`

Job Profiles

Provides access to job profiles

API URI	Description
jobprofiles	Retrieve a list of job profiles for the organization

Certificates

Provides access to training certificates

API URI	Description
employees/{id}/certificates	Retrieve a list of certificates by employee id
employees/{employeeId}/certificates	Adds a certificate for an employee
employees/{employeeId}/certificates/{id}	Updates a certificate
employees/{employeeId}/certificates/{id}	Deletes A certificate
employees/{employeeId}/certificates/{id}/attachment	Upload an attachment for a certificate. For this endpoint you must attach a multipart content containing the file to the request.
employees/{employeeId}/certificates/{id}/attachment	Download An attachment for a certificate
employees/{employeeId}/certificates/{id}/attachment	Delete the attachment of a certificate

EmployeeHours

Provides access to Employee Hours for any year beyond 2013 (2014+ inclusive).

API URI	Description
employeehours/{year}	Get year worth of Employee Hours records for your organization or a single site by adding filter ?siteId={siteId}
employeehours	Adding or Updating existing Employee Hours records

Diagnostic / Status

Provides access to diagnostic and testing information

API URI	Description
status	Checks the current status of the eCMS API.

Permission Groups

Provides access to permission groups

API URI	Description
permissiongroups	Retrieve a list of permission names available

Employees

Provides access to employees

API URI	Description
employees	Retrieve a list of employees by filtering on a limited set of URI parameters.
employees/{id}	Retrieve an employee by ID
employees	Updates all information in one employee profile. This endpoint replaces all information on the record, so fields which are not specified will be cleared. First name, last name and email cannot be modified for employee profiles which correspond to users who can log in to the system.
employees	Adds a single employee.
employees/import	Imports a list of employees.
employees/ImportExcelFile	Import employees from an excel file.
employees/{id}/terminate/{terminationDate}	Terminate an employee by ID on a specific date, or the current date if no date is provided
employees/ProfileInfo/{id}	Retrieve basic employee information. Although similar to employees/{id} it's recommended to use employees/{id}

Training

Provides access to training

API URI	Description
Training/GetTrainingFor/{id}	Retrieve training for an employee. Training is represented as a card. A card represents a course. If the employee has a certificate for a course it will be on the card. If the training is required it will be indicated on the card.

Site Memberships

Provides access to site memberships

API URI	Description
SiteMemberships/GetMembershipsFor/{id}	Retrieves site memberships for an employee.

Site Memberships

API URI	Description
SiteMemberships/GetMembershipsFor/{id}	Retrieves site memberships for an employee.

Assets

Create, update, and delete assets

API URI	Description
assets	Retrieve a list of assets for the organization
assets/{id}	Retrieve an asset by id
assets/{id}/DownloadFile/{fileId}	Retrieve an attachment for an asset
assets	Add a single asset.
assets	Update a single asset.
assets/{id}	Delete a single asset.
assets/{id}/image	Upload an image for an asset.
assets/Validate	Validate a list of assets
assets/Import	Import multiple assets

Meetings

Provides access to meetings

API URI	Description
meetings/{id}	Retrieve a meeting by ID
meetings	Retrieve a list of meetings by filtering on a limited set of URI parameters.
meetings/{id}/pdf	Retrieve a PDF of the requested meeting, by ID
meetings/{id}/DownloadFile/{fileId}	Retrieve an attachment for a meeting, by ID

Sites

Provides access to site information

API URI	Description
sites	Retrieves a list of all sites the requester has access to

Hazard Assessments

Provides access to Hazard Assessments

API URI	Description
hazardassessments/{id}	Retrieve a Hazard Assessment by ID

Training Requirements

Provides access to training requirements

API URI	Description
employees/{id}/trainingrequirements	Retrieve a list of training requirements by employee id
employees/{id}/TrainingRequirements/{trainingRequirementId}	Delete the trainingRequirement of the employee
employees/{id}/trainingrequirements	Update a training requirement

Incidents

Provides access to incident forms

API URI	Description
incidents/{id}	Retrieves an incident by ID
incidents	Retrieves a list of incidents by filtering on a limited set of URI parameters
incidents/{id}/pdf	Retrieves a PDF of the requested incident, by ID
incidents/{id}/DownloadFile/{fileId}	Retrieves an attachment for an incident, by ID

Inspections

Provides access to inspections

API URI	Description
inspections/{id}	Retrieve an inspection by ID
inspections	Retrieve a list of inspections by filtering on a limited set of URI parameters
inspections/{id}/pdf	Retrieve a PDF of the requested inspection, by ID
inspections/{id}/DownloadFile/{fileId}	Retrieve a file attachment for an inspection, by the ID

AttachmentsV1

Provides access to documents

API URI	Description
Attachments/Upload	Upload an attachment to the current site. For this endpoint you must attach a multipart content containing the file to the request.
Attachments/Download	Download a document by it's id Attachments/Download?documentId={id}

Asset Group

Provides access to asset groups

API URI	Description
assetgroups	Retrieve a list of asset groups for the organization
assetgroups/{id}	Retrieve an asset group by id
assetgroups/{id}/assettypes	Retrieve a list of asset types for the organization by group id
assetgroups	Update a single asset group.
assetgroups/validate	Validate that list of asset groups are ready to import
assetgroups/import	Import list of asset groups
assetgroups	Add a single asset group.
assetgroups/{id}	Delete a single asset group.

Courses

Provides access to courses

API URI	Description
courses	Get a list of courses

Asset Types

Provides access to asset types

API URI	Description
assettypes	Retrieve a list of asset types for the organization
assettypes/{id}	Retrieve an asset type by id
assettypes/{id}/DownloadFile/{fileId}	Retrieve an image for an asset type
assettypes/summaries	Retrieve a list of asset types summaries for the organization
assettypes	Add a single asset type.
assettypes	update a single asset type.
assettypes/Validate	Validate asset types before you attempt to import
assettypes/Import	Import asset types
assettypes/{id}	Delete a single asset type.
assettypes/{id}/image	Upload an image for an asset type.

Action Items

Provides accesss to action items and their attachments

API URI	Description
actionitems	Get a list of action items
actionitems/{id}/Attachments	Get list of attachments for a specified action item
actionitems/{id}/attachment/{attachmentId}	Retrieve an attachment for an action item