Your First Organizational Structure Integration

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)
• Completed the Your first API call tutorial

Step 1: Authenticate with department and external reference scopes

We need to read and write departments, and to register our own department code with the external references endpoints.

Request

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-departments.read connector-protimeapi-departments.write connector-protimeapi-external-references.write

Verify: The response contains an access_token with all three scopes listed.

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

We’ll use this token for all remaining steps.

Step 2: Create a department

Our ERP has a new department, Production, known there by the code D-PROD. Let’s create it in Protime, with a Dutch and a French name.

Request

POST /connector/protimeapi/api/v1/departments HTTP/1.1
Host: acme.myprotime.eu
Authorization: Bearer eyJ...Uc
Content-Type: application/json

{
  "name": {
    "default": "Production",
    "translations": {
      "nl": "Productie",
      "fr": "Production"
    }
  },
  "externalCode": "PROD-01"
}

Verify: You should see a 201 Created response. The Location header contains the URL of the new department, and the body is empty.

HTTP/1.1 201 Created
Location: /connector/protimeapi/api/v1/departments/825

name.default is the only required field. The last segment of the Location header, 825, is the Protime ID of the department. We need it once, in the next step.

Step 3: Link the department to your own code

Departments have no predefined external references, so we register our ERP code as a custom reference. We’ll name the reference ERPDEPT and link the value D-PROD to department 825.

Request

PUT /connector/protimeapi/api/v1/external-references/departments/ERPDEPT/D-PROD HTTP/1.1
Host: acme.myprotime.eu
Authorization: Bearer eyJ...Uc
Content-Type: application/json

{
  "internalReference": "825"
}

Verify: You should see a 200 OK response. From now on, D-PROD identifies department 825 wherever the API accepts a departments reference.

Step 4: Retrieve the department by your code

We put our own code in the URL, and name the collection and the reference in the externalReferences query parameter.

Request

GET /connector/protimeapi/api/v1/departments/D-PROD?externalReferences=(departments,ERPDEPT) HTTP/1.1
Host: acme.myprotime.eu
Authorization: Bearer eyJ...Uc

Verify: The response is the Production department. The API resolved D-PROD to department 825 for us.

{
  "changeVersion": "0001A3F20000B1C40021",
  "id": 825,
  "name": {
    "default": "Production",
    "translations": {
      "nl": "Productie",
      "fr": "Production"
    }
  },
  "externalCode": "PROD-01"
}

Step 5: Start a delta on departments

Before we change anything, let’s start tracking changes. We add the delta query parameter to the list endpoint. The departments delta takes no filter – it always covers all departments.

Request

GET /connector/protimeapi/api/v1/departments?delta HTTP/1.1
Host: acme.myprotime.eu
Authorization: Bearer eyJ...Uc

Verify: The response contains a value array with the current departments, Production included. If there is a nextLink, we follow it until we reach a page that carries a deltaLink instead. That final page signals we have consumed all initial data:

{
  "value": [
    {
      "changeVersion": "0001A3F20000B1C40021",
      "id": 825,
      "name": {
        "default": "Production",
        "translations": {
          "nl": "Productie",
          "fr": "Production"
        }
      },
      "externalCode": "PROD-01"
    }
  ],
  "deltaLink": "/connector/protimeapi/api/v1/delta/departments?deltaToken=eyJkZWx0YUlkIjo4MTIsInN0YXJ0aW5nQ3Vyc29yIjowLCJ0aW1lU3RhbXAiOiIyMDI2LTEwLTEyVDA5OjAwOjAwLjAwMDAwMDBaIn0="
}

Save that deltaLink – it is our bookmark for Step 7.

Step 6: Update the department by your code

Production has been renamed to Production East in our ERP. We address the department with the same code, this time on a PUT.

Request

PUT /connector/protimeapi/api/v1/departments/D-PROD?externalReferences=(departments,ERPDEPT) HTTP/1.1
Host: acme.myprotime.eu
Authorization: Bearer eyJ...Uc
Content-Type: application/json

{
  "name": {
    "default": "Production East",
    "translations": {
      "nl": "Productie Oost",
      "fr": "Production Est"
    }
  },
  "externalCode": "PROD-01"
}

Verify: You should see a 200 OK response with an empty body.

We send the complete object, including the unchanged externalCode: the update applies every field of the body.

Step 7: Pick up the change through delta

Now we call the bookmark we saved in Step 5.

Request

GET /connector/protimeapi/api/v1/delta/departments?deltaToken=eyJkZWx0YUlkIjo4MTIsInN0YXJ0aW5nQ3Vyc29yIjowLCJ0aW1lU3RhbXAiOiIyMDI2LTEwLTEyVDA5OjAwOjAwLjAwMDAwMDBaIn0= HTTP/1.1
Host: acme.myprotime.eu
Authorization: Bearer eyJ...Uc

Verify: The response contains the renamed department as an InsertOrUpdate change, with a new deltaLink.

{
  "value": [
    {
      "changeType": "InsertOrUpdate",
      "data": {
        "changeVersion": "0001A3F20000B1C40034",
        "id": 825,
        "name": {
          "default": "Production East",
          "translations": {
            "nl": "Productie Oost",
            "fr": "Production Est"
          }
        },
        "externalCode": "PROD-01"
      }
    }
  ],
  "deltaLink": "/connector/protimeapi/api/v1/delta/departments?deltaToken=eyJkZWx0YUlkIjo4MTIsInN0YXJ0aW5nQ3Vyc29yIjoyMDQ1LCJ0aW1lU3RhbXAiOiIyMDI2LTEwLTEyVDA5OjA1OjAwLjAwMDAwMDBaIn0="
}

Delta records identify the department by its Protime id: 825, the ID we linked to D-PROD in Step 3. Each response replaces the previous deltaLink – store the new one for your next poll.

What you’ve accomplished

• Authenticated with department and external reference scopes
• Created a department and linked it to your own department code
• Retrieved and updated the department by that code
• Started a delta on departments and picked up the update as an InsertOrUpdate change

Employers, jobs, job categories, sectors and work locations follow the same pattern, each with its own scopes and its own collection name in the URL and in the external references endpoint.

Next steps

• Your First People Integration – assign a person to a department
• Real-time sync with webhooks – replace delta polling with push notifications
• Departments reference – full endpoint and property documentation
• How to use external references – listing and deleting custom references