> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twine.se/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Integrate with Twine's public API

Welcome to the Twine Public API reference. Use this API to read data from Twine, and to write data back for supported domains.

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Provision access tokens from a refresh token and authenticate your requests.
  </Card>

  <Card title="Filtering and ordering" icon="filter" href="/api-reference/filtering-and-ordering">
    Filter and order results on supported list endpoints.
  </Card>

  <Card title="Pushing data" icon="upload" href="/api-reference/pushing-data">
    Considerations when writing data back to Twine.
  </Card>

  <Card title="OpenAPI specification" icon="gear" href="https://api.twine.se/spec/openapi.json">
    View the raw OpenAPI specification file.
  </Card>
</CardGroup>

## 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](/platform/other/data-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 optional `valid_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 receiving `429 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 a `403 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 a `200 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

<AccordionGroup>
  <Accordion title="Do you have a sandbox environment?">
    Yes. Please contact Twine support to get access.
  </Accordion>

  <Accordion title="Are there webhooks?">
    Not yet, but it is on the roadmap.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>