Introduction

The 7shifts API is a REST API over HTTPS. Every request goes to https://api.7shifts.com/v2, carries a bearer token and an x-api-version header, and returns JSON — including errors.

Make your first request:

curl --request GET \
  --url 'https://api.7shifts.com/v2/whoami' \
  --header 'Authorization: Bearer {ACCESS_TOKEN}' \
  --header 'x-api-version: 2026-01-01'

GET /v2/whoami returns the identity your token belongs to, including the company ID you will need for nearly every other endpoint. If it returns 200, your setup is correct.

Choose an authentication method

Create an access token. Any 7shifts customer can create one for their own company from the 7shifts web app, with no approval step.

OAuth clients are a separate credential, issued only to vetted 7shifts partners after commercial review and technical certification. They exist so one integration can serve many companies. If you are building for your own company, you do not need one.

graph TD
    A[Who will use this integration?] --> B[Just my own company]
    A --> C[Many 7shifts customers,<br/>distributed as a product]
    B --> D[Create an access token]
    C --> E[Apply to the 7shifts<br/>partner program]
    E --> F[After commercial review and<br/>technical certification,<br/>7shifts issues an OAuth client]

Full setup for both is on Authentication. To start the partner process, see Become a Partner.

Request conventions

Set x-api-version explicitly even though tokens carry a default. The default can differ from the version you built against, and the resulting failures are hard to trace.

Anatomy of a request

sequenceDiagram
    participant Y as Your system
    participant A as 7shifts API
    Y->>A: GET /v2/company/{COMPANY_ID}/time_punches?limit=20
    Note over Y,A: Authorization: Bearer {ACCESS_TOKEN}<br/>x-api-version: 2026-01-01
    A-->>Y: 200 — data[] plus meta.cursor
    Y->>A: Same request with cursor=meta.cursor.next
    A-->>Y: 200 — next page
    Note over Y: Stop when meta.cursor.next is null

List endpoints use keyset pagination through limit and cursor. See Pagination.

Errors

Errors use standard HTTP status codes with a JSON body containing status, message, and a machine-readable error field. Handle 429 with backoff. Full status and error-type tables are on Errors.

Keep credentials server-side

The API supports CORS, so browser requests work. Do not use that to call the API from client-side code with a real credential. Access tokens, OAuth client secrets, and OAuth tokens must stay on your server; anything shipped to a browser is public. If a credential is exposed, rotate it immediately.

Where to go next

Using the 7shifts API means agreeing to the 7shifts API Terms of Use.