Create, update, and delete resources

This guide covers how to create, update, and delete resources in the Protime API using POST, PUT, and DELETE requests.

Before you begin

• Obtain a valid access token. See Authenticate.
• Required scopes: a .write scope for the target collection (e.g. connector-protimeapi-clockings.write).
• Review the resource schema on the Swagger UI to know which fields are required.

Create a resource (POST)

Create a resource by sending a request to the collection endpoint with the resource attributes in the JSON body.

Host: <tenant>.myprotime.eu
Authorization: Bearer eyJ...Uc
Content-Type: application/json
User-Agent: YourService/v1 (YourCompany)

{
  "attribute": "value"
}

A successful response returns 201 Created with a Location header pointing to the new resource.

Example – create an InOut clocking:

POST /connector/protimeapi/api/v1/clockings HTTP/1.1
Host: <tenant>.myprotime.eu
Authorization: Bearer eyJ...Uc
Content-Type: application/json

{
  "person": { "id": 76547 },
  "date": "2024-01-05",
  "timeOfDayInMinutes": 480,
  "terminal": { "id": 765 },
  "geolocation": {
    "longitude": 4.392225,
    "latitude": 51.144127
  },
  "kind": "InOut"
}

201 Created
Location: /connector/protimeapi/api/v1/clockings/8192

Update a resource (PUT)

Update a resource by sending a request to the specific resource URI. Include all non-read-only fields in the body – partial updates are not supported.

Host: <tenant>.myprotime.eu
Authorization: Bearer eyJ...Uc
Content-Type: application/json

{
  "attribute": "value"
}

A successful response returns 200 OK.

Create or update a resource (PUT)

Some endpoints use PUT to either create or update a resource depending on whether the given ID already exists.

• If the ID matches an existing resource, it is updated (returns 200).
• If the ID does not exist, a new resource is created (returns 201).

This pattern is commonly used with external references. See Use external references.

PUT /connector/protimeapi/api/v1/<resource-collection>/<resource-id> HTTP/1.1
Host: <tenant>.myprotime.eu
Authorization: Bearer eyJ...Uc
Content-Type: application/json

{
  "attribute": "value"
}

Delete a resource (DELETE)

Delete a resource by sending a request to the specific resource URI.

Host: <tenant>.myprotime.eu
Authorization: Bearer eyJ...Uc
User-Agent: YourService/v1 (YourCompany)

A successful response returns 200 OK or 204 No Content, depending on the collection. Check the collection reference for the exact status code each endpoint returns.

Related

• Responses reference – full list of status codes and error format
• Fetch resources – how to retrieve data with filters and pagination
• Use external references – create-or-update with external IDs