Clockin - Customer API Examples

Here you will find some examples for consuming the Customer API

Note

• You have to generate an API Key in the Admin Panel first
• The date values ​​all correspond to the ISO 8601 format even when you call the API
• The result set is limited to 50 (currently) per default but you can overwrite this value with the limit query Parameter with a max value of 150

Employees

Creating Employee with specific Role and Workplan

curl --location 'https://customerapi.clockin.de/v3/employees?include=superior' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data-raw '{
    "last_name": "Meier",
    "first_name": "Hans",
    "email": "hmeier@example.de",
    "password": "mysecretpassword",
    "brutto_month": 3500.00,
    "gender": "MR",
    "region": "Hessen",
    "country": "IT",
    "languages": [
        "DE",
        "IT"
    ],
    "max_vacation_days": [
        {
            "year": 2024,
            "days": 30
        },
        {
            "year": 2023,
            "days": 28
        }
    ],
    "superior_id": 4,
    "nationality": [
        "DE",
        "IT"
    ],
    "income_tax_class": 1,
    "work_education": "VOCATIONAL_TRAINING",
    "marital_status": "MARRIED",
    "role_template_name": "Projektleiter",
    "work_plan": {
        "name": "Mustermann Arbeitsplan",
        "date": "2023-08-16"
    },
    "custom_fields": [
        {
            "custom_field_id": 1,
            "value": "EMP-2024-005"
        },
        {
            "custom_field_id": 2,
            "value": "Senior"
        }
    ]
}'

Add files to employee

curl --location 'https://customerapi.clockin.de/v3/employees/<EmployeeId>/files' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data '{
    "category": "jobreferences",
    "name": "Reference.pdf",
    "base64_encoded_string": "<BASE64 Encoded String>"
}'

Get an Employee with onboarding Secret

curl --location 'https://customerapi.clockin.de/v3/employees/5?include=onboardingSecret' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>'

Get available custom fields configuration for Employees

curl --location 'https://customerapi.clockin.de/v3/employees/custom-fields' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>'

Response Example:

{
    "data": [
        {
            "id": 1,
            "label": "Employee Code",
            "data_type": "text"
        },
        {
            "id": 2,
            "label": "Department Level",
            "data_type": "text"
        },
        {
            "id": 3,
            "label": "Years of Experience",
            "data_type": "number"
        },
        {
            "id": 4,
            "label": "Contract End Date",
            "data_type": "date"
        }
    ]
}

Get an Employee with custom field values

curl --location 'https://customerapi.clockin.de/v3/employees/5?include=customFields' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>'

Response Example (partial):

{
    "data": {
        "id": 5,
        "first_name": "Hans",
        "last_name": "Meier",
        "email": "hmeier@example.de",
        "...": "...",
        "customFields": [
            {
                "custom_field_id": 1,
                "label": "Employee Code",
                "data_type": "text",
                "value": "EMP-2024-005"
            },
            {
                "custom_field_id": 2,
                "label": "Department Level",
                "data_type": "text",
                "value": "Senior"
            },
            {
                "custom_field_id": 3,
                "label": "Years of Experience",
                "data_type": "number",
                "value": "8"
            },
            {
                "custom_field_id": 4,
                "label": "Contract End Date",
                "data_type": "date",
                "value": "2025-12-31T00:00:00.000000Z"
            }
        ]
    }
}

Search Employees with custom fields included

curl --location 'https://customerapi.clockin.de/v3/employees/search?include=customFields' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data '{
  "scopes": [
    {
      "name": "byLastName",
      "parameters": ["Meier"]
    }
  ]
}'

Response includes customFields array for each employee in the same format as shown above.

Projects

Fetching Projects including employees and subprojects with a limit of 100

curl --location 'https://customerapi.clockin.de/v3/projects?include=employees,subProjects&limit=100' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>'

Fetching uncompleted projects regarding createdAt

curl --location 'https://customerapi.clockin.de/v3/projects/search' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data '{
  "scopes": [
    {
      "name": "byCreatedAt",
      "parameters": [
          ">=",
          "2023-08-08T11:30:00.000000Z"
      ]
    },
    {
      "name": "uncompleted",
    }
  ]
}'

Fetch projects updated or created since 2023-08-21T13:35:58.000000Z

curl --location 'https://customerapi.clockin.de/v3/projects/search' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data '{
  "scopes": [
    {
      "name": "byUpdatedAt",
      "parameters": [
          ">=",
          "2023-08-21T13:35:58.000000Z"
      ]
    }
  ]
}'

Fetch project with signed URL (open link to the Project)

curl --location 'https://customerapi.clockin.de/v3/projects/<PROJECT_ID>?include=signedUrl' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>'

Add Tags to Project

curl --location --request PATCH 'https://customerapi.clockin.de/v3/projects/86' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data '{
    "projectTags": [
        "NewTagName"
    ]
}'

Attach Employees 1,2 to Project 14

curl --location 'https://customerapi.clockin.de/v3/projects/14/employees/attach' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data '{
    "resources": [
        1,2
    ]
}'

Create Attachment for Project

curl --location 'https://customerapi.clockin.de/v3/projects/11/files' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data '{
    "title": "Invoice.pdf",
    "base64_encoded_string": "<BASE64 encoded String>"
}'

Fetch project files

curl --location 'https://customerapi.clockin.de/v3/projects/1/files/search' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 2|hKPqA7bIQ5EuW8hsKwZTYIySBRlBqWihHNRyQL4W' \

Fetch only notes sorted by createdAt for project

curl --location 'https://customerapi.clockin.de/v3/projects/1/files/search' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 2|hKPqA7bIQ5EuW8hsKwZTYIySBRlBqWihHNRyQL4W' \
--data '{
  "scopes": [
    {
      "name": "byTypes",
      "parameters": [
          "note"
      ]
    }
  ],
  "sort": [
    {
      "field": "created_at",
      "direction": "desc"
    }
  ]
}'

Absences

Create granted Absence

curl --location 'https://customerapi.clockin.de/v3/absences' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data '{
    "employee_id": 1,
    "absencecategory_name": "workshop",
    "starts_at": "2023-09-21T15:00:00Z",
    "ends_at": "2023-09-21T18:00:00Z",
    "approval": "granted",
    "duration": "start_end"
}'

Search absences by starts at

curl --location 'https://customerapi.clockin.de/v3/absences/search' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data '{
  "scopes": [
    {
      "name": "byStartsAt",
      "parameters": [
          ">=",
          "2032-08-09T14:00:00.00Z"
      ]
    }
  ]
}'

Search Absences by approval states

curl --location 'https://customerapi.clockin.de/v3/absences/search' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data '{
  "scopes": [
    {
      "name": "byApprovals",
      "parameters": [
          "granted",
          "pending"
      ]
    }
  ]
}'

Events

Create event for the task WORKING_TIME

curl --location 'https://customerapi.clockin.de/v3/events' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data '{
    "occured_at": "2023-11-28T10:45:30+01", 
    "task_id": 10,
    "employee_id": 5
  }'

Create event for the task WORKING_TIME with a custom task Label

Only pre configured task label / task id combinations are valid, you can configure it here https://office.clockin.de/setting/tasks

curl --location 'https://customerapi.clockin.de/v3/events' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data '{
    "occured_at": "2023-11-28T10:45:30+01", 
    "task_id": 10,
    "task_label": "Arbeitszeit2"
    "employee_id": 5
  }'