menu

Overview

This describes the resources and specifications that make up the Insperity Public API. If you have any problems or requests please contact support.

Connection Setup & Testing

To create your first API integration, contact an Insperity Integration Specialist.

Checklist:

  • Sign the API Terms of Use Agreement
  • Provide Insperity client IDs
  • Provide a list of IP addresses or IP range for whitelisting
  • Insperity Integration Specialist will create an API Connection
  • Insperity will send a secure key to be used in all API requests

It is important that requests utilize the stage environment URL and they must contain an Insperity client ID. If the client ID is missing, the request will be rejected.

Stage

https://apistage.insperity.com

Production

https://api.insperity.com

In stage, testing is coordinated with your Integrations Specialist as access to internal systems is restricted. Onboarding or employee change results will be sent upon request or we can facilitate an end to end testing meeting. Records in stage resemble production but sensitive information is de-identified for security.

Once approved, a new production URL/Key combination will be sent.

Version

All requests need to explicitly state the version in each request. Version is a component of API uri.

Example

https://api.insperity.com/public/employee/addresschange/v1

messageFor information about latest version, see the API Explorer.

Schema

  • All API use HTTPS and are accessed through https://api.insperity.com.
  • All data is sent and received as JSON.
  • Blank fields should be omitted.
  • All time is ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

Parameters

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

Example

curl -H 'Authorization: APIKey {YourApiKey}' 'https://api.insperity.com/public/employee/addresschange/v1'

For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of 'application/json':

Filtering

To specify a filter on an API the filter parameter must be added to the query string.

Example Filter Uri

https://{URL}/company/{CompanyID}/{API}/v1?filter={filter criteria}

Filter Criteria must follow the following format:

Filter Format

filter={filterable property} {comparison operator} "{value}"

Comparison Operators

Operator Description Example
eq Equal employmentStatus eq "HIRED"
ne Not equal employmentStatus ne "TERMINATED"
gt Greater Than changeDate gt "2020-09-21 14:45:26"
lt Less Than changeDate lt "2020-09-21 14:45:26"
contains The value contains the provided filter value position.jobCategory contains "Supervisor"
startswith The value starts with the provided filter value position.jobCategory startswith "Sales"
endswith The value ends with the provided filter value position.jobCategory endswith "Director"

Value comparisons are case-sensitive.

Multiple filters can be combined using the conditional operators and and or.

Example Combined Filter

filter=employmentStatus eq "HIRED" and position.jobCategory startswith "F"

Filterable Properties depend on the API being called. If you attempt to filter on a non-filterable property you will receive an error message stating: {property} is a non-filterable field

When filtering on properties that exist in a sub-class of employee data you must use dot notation to filter on the category. For example the jobCategory field is a property of position in the employee data, so to filter on jobCategory you must use position.jobCategory.

Sorting

To specify a sort on the data returned the sort tag must be added to the API URL.

Example Sort URL

https://{URL}/company/{CompanyID}/{API}/v1?sort={sort criteria}

Sort Criteria must follow the following format: sort={sortable property} [{asc | desc}]

Sortable properties depend on the API being called and any attempt to filter on a non-sortable property will result in an error message: Invalid Sort Criterion: {property name}

The default sort direction is ascending; however, you can optionally specify sort direction by following the property name with either ASC or DESC.

HTTP Status Codes

The following HTTP status codes could be returned when making API calls:

Status Code Description
200 The request was a success
400 There was a problem with the incoming data
401 Authentication failed
403 Unauthorized
404 The requested resource does not exist
422 Unprocessable entity
500 Internal system error

POST - Expected JSON Elements & Values

The following are required elements for all incoming POST actions and their expected values.

Parent Element: employerIdentifier.organizationID

  • This is used in all Insperity API calls
Element Description Example
schemeID This value should always be "InsperityCompanyID". "InsperityCompanyID"
schemeAgencyID This value should always be "Insperity". "Insperity"
value This value will be the client ID provided to you by Insperity. "1234567"

Parent Element: personLegalID

  • A person legal ID can be either the person's ITIN or SSN
Element Description Example
schemeID This value should be either "SocialSecurityNumber" or "ITIN". "SocialSecurityNumber"
schemeAgencyID This value should be either "US-SSA" or "US-IRS". "US-SSA"
value This is either the person's SSN or ITIN. "999-99-9999"

Parent Element: personIdentifier.personID - Using Insperity Person ID

  • This can be used in all APIs except Onboarding where the person does not yet have an Insperity ID.
Element Description Example
schemeID This value should always be "InsperityPersonID". "InsperityPersonID"
schemeAgencyID This value should always be "Insperity". "Insperity"
value This is the Insperity Employee number. "9999999"

Parent Element: personIdentifier.personID - Using your application's unique Employee ID For Onboarding

  • This only applies to Onboarding API calls.
Element Description Example
schemeID The value should be company name followed by 'PersonID'. "MyCompanyPersonID"
schemeAgencyID The value should be your company name. "MyCompany"
value This is the person's unique ID number in your environment. "093-0293874"

API Transaction Status

Check API transaction status.

Example

https://api.insperity.com/public/transaction/{trackingId}/status

Tracking ID is returned as part of the API response body.

Example Response

{
                "trackingId": "479841b4-f2f3-451e-82e7-4c32f6228e8b",
                "dateReceived": "2018-11-19 11:51:19 AM",
                "primaryStatus": "Success",
                "dateStatused": "2018-11-19 11:51:25 AM",
                "detailsMessages":[
                "Success: 1"
                ],
                "details":[
                {
                "personId": 1234567,
                "event": "Employee.SupervisorChange",
                "status": "Success"
                "statusDate": "2018-11-19 11:51:25 AM"
                }
                ]
}

Responses can be Success, Failed, In Progress, Authenticated and Error.

Client Errors

There are three possible types of client errors on API calls that receive request bodies:

Sending invalid JSON will result in a 400 Bad Request response.

Example Response

HTTP/1.1 400 Bad Request
Content-Length: 35
{ "message" : "Problems parsing JSON" }

Sending the wrong type of JSON values will result in a 400 Bad Request response.

Example Response

HTTP/1.1 400 Bad Request
Content-Length: 40
{ "message" : "Body should be a JSON object" }

Sending invalid fields will result in a 422 Unprocessable Entity response.

Example Response

HTTP/1.1 422 Unprocessable Entity
Content-Length: 149
{
                "message": "Validation Failed",
                "errors": [
                {
                "resource": "Issue",
                "field": "title",
                "code": "missing_field"
                }
                ]
}

All error objects have resource and field properties so that your company can tell what the problem is. There's also an error code to let you know what is wrong with the field.

Error Codes

Error Name Description
missing This means a resource does not exist.
missing_field This means a required field on a resource has not been set.
invalid This means the formatting of a field is invalid. The documentation for that resource should be able to give you more specific information.
already_exists This means another resource has the same value as this field. This can happen in resources that must have some unique key (such as Label names).

Resources may also send custom validation errors (where code is custom). Custom errors will always have a message field describing the error, and most errors will also include a documentation_url field pointing to some content that might help you resolve the error.

HTTP Verbs

Where possible, Insperity API strives to use appropriate HTTP verbs for each action.

Verb Description
GET Used for retrieving resources.
POST Used for creating resources.
PATCH Used for updating resources with partial JSON data. For instance, an Issue resource has title and body attributes. A PATCH request may accept one or more of the attributes to update the resource. PATCH is a relatively new and uncommon HTTP verb, so resource endpoints also accept POST requests.
PUT Used for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero.
DELETE Used for deleting resources.

Authentication

Currently there is only one way to authenticate through Insperity API. Authentication requests can return either 404 Not Found or 403 Forbidden depending on the situation. This is to prevent the accidental release of sensitive information to unauthorized users.

API Key with IP Whitelisting

curl -H 'Authorization: APIKey {YourApiKey}' 'https://api.insperity.com/public/employee/addresschange/v1'

warning Don't leak your API KEY to your users.