Tutorials
Your First Assignment Integration

Your First Assignment Integration

What you’ll learn: How to authenticate with assignment scopes, create a work assignment via the API, retrieve and update it, delete it when no longer needed, and set up delta tracking to detect assignment changes incrementally.

Prerequisites

Before we begin, make sure you have the following:

  • A tenant name for your Protime environment (e.g. acme from https://acme.myprotime.eu)
  • An OAuth2 client_id and client_secret provided by Protime
  • A tool for making HTTP requests (e.g. curl, Postman, or your programming language of choice)
  • The person ID of an employee in your Protime environment (we’ll use 1 in this tutorial)
  • Completed the Your first API call tutorial
The assignments endpoints are only available if your tenant is not using Planning Flex or Shift. If you receive a 403 Forbidden response, check with your Protime administrator.

Step 1: Authenticate with read and write scopes

We need both read and write permissions for assignments. Let’s request a token with both scopes.

Request

POST
https://authentication.<environmentURL>/tenants/<tenantName>/connect/token

POST /tenants/acme/connect/token HTTP/1.1
Host: authentication.myprotime.eu
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret&scope=connector-protimeapi-assignments.read connector-protimeapi-assignments.write

Verify: The response contains an access_token with both scopes listed.

{
  "access_token": "eyJ...Uc",
  "expires_in": 1800,
  "token_type": "Bearer",
  "scope": "connector-protimeapi-assignments.read connector-protimeapi-assignments.write"
}

We’ll use this token for all remaining steps.

Step 2: Create an assignment

Let’s create a work assignment for person 1 on 2026-03-10, scheduled from 08:00 to 17:00 (480 to 1020 minutes since midnight) with a 30-minute break and an activity level.

Request

POST
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/assignments

POST /connector/protimeapi/api/v1/assignments HTTP/1.1
Host: acme.myprotime.eu
Authorization: Bearer eyJ...Uc
Content-Type: application/json
{
  "person": {
    "id": 1
  },
  "from": "2026-03-10",
  "until": "2026-03-10",
  "startTimeInMinutes": 480,
  "endTimeInMinutes": 1020,
  "breakDurationInMinutes": 30,
  "comments": "Morning shift",
  "activityLevels": [
    {
      "level": 1,
      "activityDefinition": {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
  ]
}

Verify: You should see a 201 Created response. The Location header contains the URL of the newly created assignment.

HTTP/1.1 201 Created
Location: /connector/protimeapi/api/v1/assignments/757085

Save the ID from the Location header (in this example, 757085). We’ll use it in the next steps.

Step 3: Retrieve the created assignment

Let’s confirm the assignment was created correctly by fetching it using the ID from the Location header.

Request

GET
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/assignments/757085

GET /connector/protimeapi/api/v1/assignments/757085 HTTP/1.1
Host: acme.myprotime.eu
Authorization: Bearer eyJ...Uc

Verify: The response matches the assignment we created, with the person, dates, times, and break all reflecting our input.

{
  "changeVersion": "0001E7C5000098FA0013",
  "id": 757085,
  "isRejected": false,
  "person": {
    "id": 1
  },
  "from": "2026-03-10",
  "until": "2026-03-10",
  "startTimeInMinutes": 480,
  "endTimeInMinutes": 1020,
  "breakDurationInMinutes": 30,
  "comments": "Morning shift",
  "activityLevels": [
    {
      "level": 1,
      "activityDefinition": {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
  ]
}

The changeVersion field is assigned by the system and tracks modifications to this assignment.

Step 4: Update the assignment

The schedule has changed — the shift now runs from 09:00 to 18:00 with a longer break. Let’s update the assignment using the same ID.

Request

PUT
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/assignments/757085

PUT /connector/protimeapi/api/v1/assignments/757085 HTTP/1.1
Host: acme.myprotime.eu
Authorization: Bearer eyJ...Uc
Content-Type: application/json
{
  "person": {
    "id": 1
  },
  "from": "2026-03-10",
  "until": "2026-03-10",
  "startTimeInMinutes": 540,
  "endTimeInMinutes": 1080,
  "breakDurationInMinutes": 60,
  "comments": "Updated to late shift",
  "activityLevels": [
    {
      "level": 1,
      "activityDefinition": {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
  ]
}

Verify: You should see a 200 OK response, confirming the assignment was updated.

HTTP/1.1 200 OK

Let’s fetch the assignment again to confirm the changes took effect.

GET /connector/protimeapi/api/v1/assignments/757085 HTTP/1.1
Host: acme.myprotime.eu
Authorization: Bearer eyJ...Uc
{
  "changeVersion": "0001E7C5000098FA0014",
  "id": 757085,
  "isRejected": false,
  "person": {
    "id": 1
  },
  "from": "2026-03-10",
  "until": "2026-03-10",
  "startTimeInMinutes": 540,
  "endTimeInMinutes": 1080,
  "breakDurationInMinutes": 60,
  "comments": "Updated to late shift",
  "activityLevels": [
    {
      "level": 1,
      "activityDefinition": {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
  ]
}

Notice that the changeVersion has changed — the system tracks every modification.

Step 5: Delete the assignment

The shift has been cancelled. Let’s remove the assignment.

Request

DELETE
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/assignments/757085

DELETE /connector/protimeapi/api/v1/assignments/757085 HTTP/1.1
Host: acme.myprotime.eu
Authorization: Bearer eyJ...Uc

Verify: You should see a 200 OK response, confirming the assignment was deleted.

HTTP/1.1 200 OK

If we try to retrieve it again, we receive a 404 Not Found:

GET /connector/protimeapi/api/v1/assignments/757085 HTTP/1.1
Host: acme.myprotime.eu
Authorization: Bearer eyJ...Uc
HTTP/1.1 404 Not Found

Step 6: Set up delta tracking

Delta tracking lets us fetch only assignment changes since our last request. Let’s initialize a delta for assignments. A date filter is required.

Request

GET
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/assignments?filter=date ge '2026-01-01'&delta

GET /connector/protimeapi/api/v1/assignments?filter=date%20ge%20'2026-01-01'&delta HTTP/1.1
Host: acme.myprotime.eu
Authorization: Bearer eyJ...Uc

Verify: The response contains a value array with existing assignments. If there is a nextLink, we must follow it to page through all data.

{
  "value": [
    {
      "changeVersion": "0001E7C5000098FA0015",
      "id": 757086,
      "isRejected": false,
      "person": { "id": 2 },
      "from": "2026-03-11",
      "until": "2026-03-11",
      "startTimeInMinutes": 480,
      "endTimeInMinutes": 1020,
      "breakDurationInMinutes": 30,
      "activityLevels": [
        {
          "level": 1,
          "activityDefinition": {
            "id": "550e8400-e29b-41d4-a716-446655440000"
          }
        }
      ]
    }
  ],
  "nextLink": "/connector/protimeapi/api/v1/assignments?filter=date ge '2026-01-01'&continuationToken=eyJ2YW...&deltaToken=eyJkZW..."
}

We follow every nextLink until we reach a page that contains a deltaLink instead. This final page signals that we have consumed all initial data.

{
  "value": [],
  "deltaLink": "/connector/protimeapi/api/v1/delta/assignments?deltaToken=eyJkZWx0YUlkIjo2NzcsInN0YXJ0aW5nQ3Vyc29yIjowfQ=="
}

Verify: The response contains a deltaLink field. Save this URL — it is our bookmark for tracking future changes.

We then call the deltaLink to retrieve changes. Each delta response includes changeType (InsertOrUpdate or Delete) and a new deltaLink for the next poll.

{
  "value": [
    {
      "changeType": "Delete",
      "data": {
        "changeVersion": "0001E7C5000098FA0016",
        "id": 757085
      }
    }
  ],
  "deltaLink": "/connector/protimeapi/api/v1/delta/assignments?deltaToken=eyJkZWx0YUlkIjo2NzcsInN0YXJ0aW5nQ3Vyc29yIjoxMjM0fQ=="
}

The delete we performed in Step 5 appears as a Delete change event.

Caution

A delta expires after 72 hours. You must call the deltaLink at least once within that window, even if you expect no changes, to keep it alive. If the delta expires, the API returns 410 Gone and you must reinitialize from the beginning of this step.

Note

Delta requests for assignments can only filter on date. The person filter cannot be used with delta.

What you’ve accomplished

  • Authenticated with both read and write scopes for assignments
  • Created a work assignment with person, date, time, and break details
  • Retrieved the assignment to confirm creation
  • Updated the assignment’s schedule and verified the change
  • Deleted the assignment and confirmed removal
  • Initialized delta tracking and observed the delete appear as a change event
  • Learned how to chain deltaLink values for ongoing synchronization

Next steps

Related concepts

Your First Clocking IntegrationReal-time Sync with Webhooks