Authentication
Provision access tokens from a refresh token and authenticate your requests.
Filtering and ordering
Filter and order results on supported list endpoints.
Pushing data
Considerations when writing data back to Twine.
OpenAPI specification
View the raw OpenAPI specification file.
Versioning
The API is versioned. The current version is v1.1, served under the/v1 path. As the API is subject to change, new versions may be released. Always refer to the latest documentation to ensure you’re using the correct version.
Dated model attributes
In v1.1, every entity field is tracked by change date. This allows you to fetch data as it existed at a specific point in time, or retrieve all changes from a specific point in time up to the present. For employees, you can also supply a shape to get the data in a format that suits your needs.Dated values
In the v1.1 model, all fields are represented by an array of values with an optionalvalid_from timestamp. A null value for valid_from indicates that the field value is valid from the beginning of time, meaning it has no recorded history in the system. When multiple values exist in the array, they are sorted in descending order with the most recent value first. The last value may or may not have a null timestamp. An array can never contain more than one value with a null timestamp.
Data reliability
A given piece of data is a snapshot of the latest data fetched from the Vendor. In some cases the data returned by Twine will be out of sync with the Vendor. This is due to the nature of the integration and the data provided by the Vendor. Twine always strives to provide the most accurate data possible. Depending on the Customer, the data may be updated in near real-time or with a longer delay.Rate limiting
The API is not currently rate limited. However, you should expect this to change in the near future. At that point you will start receiving429 Too Many Requests responses. More information will be provided here when rate limiting is implemented.
Fetching single resources
When requesting a single resource with inadequate permissions, you will receive a403 Forbidden response.
Fetching lists of resources
When requesting a list of resources, the API filters out resources you do not have access to. This means the response may contain fewer resources than expected. The API always returns a200 OK response, even if the list is empty.
Nomenclature
Throughout the API, the following terms are used:| Term | Description |
|---|---|
| Customer | The entity on whose behalf Twine processes personnel data |
| Vendor | Third party supplier of data with which Twine integrates on behalf of a Customer |
FAQ
Do you have a sandbox environment?
Do you have a sandbox environment?
Yes. Please contact Twine support to get access.
Are there webhooks?
Are there webhooks?
Not yet, but it is on the roadmap.
How can I keep the response body small?
How can I keep the response body small?
Use the
select parameter to only fetch the fields you need. This reduces the response size and speeds up the request. Combine it with filtering by updated_at to only fetch the data that has changed since your last request.