This document details important concepts and common use cases for using TriNet APIs.

Application Types

TriNet APIs can be used to create two types of applications:

  • End-user applications: The user is required to log in to TriNet to obtain access to the required resources. When a user runs an API call, it is using the individual's own credentials. Learn more about end-user applications.
  • Business-to-business (B2B) applications: These are typically system integrations. All processes occur in the background and system login is not always possible. Different security measures need to be taken. Learn more about B2B applications.

Top of the page

Authentication and Authorization

TriNet API methods require authorized access, which differs by application type.

Authorized API access (OAuth 2.0)

TriNet API calls access sensitive employee and company data. Before the application can call them, the following must be accomplished with OAuth 2.0 and the corresponding libraries:

  • Your application must be authenticated.
  • The user with access to that data must grant your application access.
  • The user must be authenticated to grant that access.

Refresh and access tokens: When a user grants your application access, the authorization server provides the application with refresh and access tokens. Your application uses access tokens to authorize API calls. Access tokens expire but refresh tokens do not. Your application can use a refresh token to acquire a new access token.

Keep your application's refresh and access tokens secure as they can be used to access sensitive data.

Client ID and client secret: These uniquely identify your company's application and are used to acquire tokens. List of scopes is also assigned to determine access level. Please visit Oauth Scopes page for more info.

Top of the page

Making Requests

  • All requests made to TriNet APIs must be sent over HTTPS. The SSL certificate used for the HTTPS connection is signed and all implementations should configure their SSL layer to verify it.
  • To make a valid request, an access token must be provided. To learn how to obtain an access token, see Business-to-Business Applications or End-User Applications.
  • Each employee has a unique employee ID that you can use to reference the employee.

Top of the page

Response Information

For every request, a response header is generated that contains important information about the request and its status. You can use the information in this header to improve your application.

Sample response header:

{
  "data": [
 .
 .
 .
  ],
  "_requestId": "df45d7bc-6394-4992-aaa8-81019466893e",
  "_statusCode": "200",
  "_statusText": "OK",
  "_statusMessage": "Success"
}

 

HTTP Status Codes

Every request includes an HTTP status code with the result. The status code should be examined before the response. TriNet adheres to the following standard codes:

200-299 Successful Status Codes

  • 200 OK: The request was successful.
  • 201 Created: The resource was successfully created. This confirms when a new record is successfully added.

400-499 Client Error Status Codes

  • 400 Bad Request: The request was invalid or could not be understood by the server. Resubmitting the request will likely result in the same error.
  • 401 Unauthorized: Your authorization information is missing.
  • 403 Forbidden: The application is attempting to perform an action it does not have privileges to perform. Verify that your application has the needed permissions to access the resource.
  • 404 Not Found: The resource was not found with the given identifier. Either the provided URL is not a valid API or the ID of the object specified in the request is invalid.

500-599 Server Error Status Codes

  • 500 Internal Server Error: The server encountered an error while processing your request and failed.

statusText and statusMessage

The statusText and statusMessage provide additional information about the status of the request. This can be useful when a request returns a 4xx error, when those fields provide additional information about the error that can be used in debugging the issue. 

requestId

The requestId is a unique identifier assigned by TriNet to the request. You may be asked to provide this ID when you contact TriNet for help with TriNet APIs. 

Top of the page

Effective Dates

Most records contain an effective date that indicates when that information or action becomes effective. A record may also have an effective end date. The record that is currently effective is available for transactions. Other records are stored as history or will take effect on a future date.

An employee can have multiple changes for the same effective date, for example, if there are two job changes that take effect on the same date.

Top of the page

TriNet Field Values

TriNet uses a number of standard codes in dropdowns and data, some of which are exposed through TriNet APIs. For a list of all static/non-company specific codes for a specific field, see Field Values.

Top of the page