Getting Started

Guardian allows the use of a RESTful endpoint structure and HTTP verbs to share data. REST APIs and are available for use by those clients whose Guardian platform configuration utilizes the hierarchical model. This model allows organizations to group and classify employees.

Guardian offers a set of application programming interfaces (APIs) that give you the means to incorporate Guardian functionality into your website applications and mobile apps.

Formats and Connections:

All dates in the API are strings in ISO 8601 format, ‘YYYY-MM-DD’. For example,
```
# December 12th, 2015
2015-12-10
```
All API access is over HTTPS.
All data is sent and received as JSON, specified as
```
Content-Type: application/json
```
All data requests should be in Unicode, specifically the Unicode (or UCS) Transformation Format, 8-bit encoding form (UTF-8).
In responses, the API always returns data in UTF-8.

Endpoints:

Our REST API is divided among several service endpoints, documented in the standard endpoints section. Each endpoint has additional request parameters that are specific to the behaviors of that service.

Links:

Many endpoints will return links to other useful results in addition to the data that is requested. For example, an employee search may include links to the first, last, next, and previous pages or an employee lookup may include a link to the i9 data for that employee (if it exists). The Guardian API uses the Collection+JSON approach to provide these additional resources as urls within the service’s results.

These links are formatted as a json collection titled “links”. Each entry in that collection will have two properties:

rel: the name or type of the link. Ex: “next” for the next page of results.
href: the url to follow for the action described by rel. This URL is relative to the server name.

All links in the format above are intended to be followed by the integrating system, not to be presented to users in a browser. Furthermore, their internal structure such as parameter order or other details should not be parsed or interpreted as they are considered internal implementation details rather than external endpoints. Integrating systems should either use only the apis defined in this document, or perform the necessary lookup and follow the system-generated link.

Authentication:

All requests require some form of authentication. Callers must authenticate through OAuth 2.0 using client access tokens. The Guardian system will authenticate itself when making outbound calls using HTTP Basic authentication. More details are available under authentication: Authentication

Versioning and Updates:

Endpoints are versioned via their url, allowing clients to choose which version to connect to. Ex: https://<server>/v1/employees specifies version 1 (v1). As LawLogix updates APIs, all updates deployed without changing the version number can be expected to be 100% backwards compatible.

Standard API Errors:

Code	Description
400	Bad input parameter. Error message should indicate which one and why.
401	Bad or expired token. This can happen if the user or Guardian revoked or expired an access token. To fix, you should re-authenticate the user.
403	The account being accessed does not have sufficient permissions to execute this operation.
404	The specified resource does not exist.
405	Request method not expected (generally should be GET, PUT or POST).
500	The server encountered an internal error.