Back to top

Payroll

If you want to integrate Beeple with a 3rd-party system that handles all the legal requirements like creating a payroll you will need to implement a HTTP service that implements the following calls (and callbacks) which will be sent by the Beeple system.

These calls will provide you for example with info every time an enrolment is added, created or modified in Beeple.

A payroll marketplace extension needs to implement all of these web calls but we leave it up to the implementation what exactly happens. It is free to ignore messages it thinks it does not need.

General remarks

General remarks like idempotency and authentication are the same between all our API’s. Have a look in webhooks to see more details.

Collaborators

List of Collaborators

Collaborator linked
POST/collaborators

This webhook will be sent every time a collaborator is linked to a given payroll account. The service can optionally reply with an ID which Beeple will store.

Note the linking can either be done explicitly by the end user, or implicit by the system when the Beeple system notices a link between the payroll and the collaborator.

It can reply with a 400 status code when the user could not be created. The response should then contain error messages about the issues. Beeple will not retry sending the same request in this case.

Other errors (especially in the 500 range) Beeple will actually retry sending the request a few times at certain intervals.

When the collaborator already exists in the target system an error should not be returned, but rather a success message. In this case the collaborator should be updated. In case the update fails the error messages can be sent.

Example URI

POST /collaborators
Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Body
{
  "company": {
    "name": "My company",
    "beeple_id": "273e949a-bb41-4f36-9526-d1d0a8043c91",
    "enterprise_number": "0101010101",
    "payroll_service_id": "5"
  },
  "collaborator": {
    "first_name": "John",
    "last_name": "Doe",
    "prefix": "De",
    "beeple_id": 2403,
    "birth_date": "1995-05-07",
    "birth_city": "Antwerpen",
    "birth_country": "BE",
    "gender": "male",
    "language": "en",
    "nationality": "BE",
    "national_registration_numbers": [
      {
        "country": "BE",
        "number": "95.05.07-997.47"
      }
    ],
    "social_statute": "Arbeider",
    "social_statute_code": "career_pause",
    "home_address": {
      "street1": "Dorpstraat 1",
      "street2": "Bus 1",
      "zip": "2018",
      "city": "Antwerpen",
      "administrative_area_level_1": "Hello, world!",
      "administrative_area_level_2": "Hello, world!",
      "administrative_area_level_3": "Hello, world!",
      "administrative_area_level_4": "Hello, world!",
      "administrative_area_level_5": "Hello, world!",
      "country": "BE"
    },
    "bank_account": {
      "iban": "BE68539007547034",
      "bic": "HBKABE22"
    },
    "blocked": false,
    "blocked_reason": "nothing to say",
    "contact": {
      "email": "john.doe@example.org",
      "mobile": "+32498525251"
    },
    "departments": [
      {
        "id": 2403,
        "name": "Accounting"
      }
    ],
    "primary_department_id": 7487,
    "primary_manager_id": 122,
    "profile_properties": [
      {
        "group": "Legal information",
        "profile_property_id": 1888,
        "name": "Marital status",
        "description": "Here you can enter your official marital status",
        "type": "boolean",
        "numeric_unit": "km",
        "value_boolean": true,
        "value_string": "Married",
        "value_list_multi": [
          "english"
        ],
        "value_date": "2017-05-08",
        "value_time": "17:00:00.000+02:00",
        "value_datetime": "2017-05-08T17:00:00.000+02:00",
        "value_numeric": 23.5,
        "value_upload_url": "https://planning.tenant.be/api/v1/uploads/volunteers/volunteers_profile_property/upload_collaborator/5916/uploaded_file.docx",
        "comment": "Since 15/5/1995",
        "expiration_date": "2017-05-08",
        "piece_of_evidence": "https://planning.tenant.be/api/v1/uploads/volunteers/volunteers_profile_property/documented_proof_verified/43413/piece_of_evidence_file.docx"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "company": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the company (tenant). Can change and is mainly for displaying purposes"
        },
        "beeple_id": {
          "type": "string",
          "description": "The ID of the Beeple Tenant (a UUID). Will never change for a given tenant."
        },
        "enterprise_number": {
          "type": "string",
          "description": "Enterprise number of this company"
        },
        "payroll_service_id": {
          "type": "string",
          "description": "A payroll service ID."
        }
      },
      "required": [
        "name",
        "beeple_id"
      ],
      "description": "Company that is sending this information."
    },
    "collaborator": {
      "type": "object",
      "properties": {
        "first_name": {
          "type": "string",
          "description": "First name"
        },
        "last_name": {
          "type": "string",
          "description": "Last name"
        },
        "prefix": {
          "type": "string",
          "description": "Last name prefix, this is what appears on the screen of the web application as \"infix\"; for example John De Doe"
        },
        "beeple_id": {
          "type": "number",
          "description": "Identification number within Beeple"
        },
        "birth_date": {
          "type": "string",
          "description": "Birth date according RFC 3339"
        },
        "birth_city": {
          "type": "string",
          "description": "Birth city"
        },
        "birth_country": {
          "type": "string",
          "description": "Birth country according to ISO 3166-1 alpha-2"
        },
        "gender": {
          "type": "string",
          "enum": [
            "male",
            "female"
          ],
          "description": "Gender"
        },
        "language": {
          "type": "string",
          "description": "Language in which to communicate with the collaborator according to ISO 639-1"
        },
        "nationality": {
          "type": "string",
          "description": "According to ISO 3166-1 alpha-2"
        },
        "national_registration_numbers": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "country": {
                "type": "string",
                "description": "Country for which the number is valid according to ISO 3166-1 alpha-2"
              },
              "number": {
                "type": "string"
              }
            }
          }
        },
        "social_statute": {
          "type": "string",
          "description": "The social statute"
        },
        "social_statute_code": {
          "type": "string",
          "enum": [
            "career_pause",
            "disabled_entrepreneur",
            "early_retired",
            "entrepreneur",
            "flexijobs",
            "functionary",
            "incapacitated",
            "living_wager",
            "retired",
            "student",
            "unemployed",
            "unemployed_waiting_period",
            "unknown",
            "working_class",
            "working_class_blue_collar",
            "work_student"
          ],
          "description": "The social statute"
        },
        "home_address": {
          "type": "object",
          "properties": {
            "street1": {
              "type": "string",
              "description": "Street + house number"
            },
            "street2": {
              "type": "string",
              "description": "Extension of street1"
            },
            "zip": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "administrative_area_level_1": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "administrative_area_level_2": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "administrative_area_level_3": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "administrative_area_level_4": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "administrative_area_level_5": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "country": {
              "type": "string",
              "description": "According to ISO 3166-1 alpha-2"
            }
          }
        },
        "bank_account": {
          "type": "object",
          "properties": {
            "iban": {
              "type": "string"
            },
            "bic": {
              "type": "string"
            }
          }
        },
        "blocked": {
          "type": "boolean",
          "description": "Indicates if the user is blocked"
        },
        "blocked_reason": {
          "type": "string",
          "description": "A comment posted during block or unblock"
        },
        "contact": {
          "type": "object",
          "properties": {
            "email": {
              "type": "string"
            },
            "mobile": {
              "type": "string"
            }
          },
          "required": [
            "email"
          ]
        },
        "departments": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "Identification number of the department within Beeple"
              },
              "name": {
                "type": "string",
                "description": "Name of the department"
              }
            },
            "required": [
              "id"
            ]
          },
          "description": "List of departments the collaborator belongs to"
        },
        "primary_department_id": {
          "type": "number",
          "description": "The ID of the collaborator's primary department. Will be the id of one of the collaborator's departments"
        },
        "primary_manager_id": {
          "type": "number",
          "description": "The ID of the collaborator's manager. Must be a collaborator that is an admin and has access rights to approve availabilities."
        },
        "profile_properties": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "group": {
                "type": "string",
                "description": "Group of profile properties"
              },
              "profile_property_id": {
                "type": "number",
                "description": "Id of the profile property"
              },
              "name": {
                "type": "string",
                "description": "Name of the profile property"
              },
              "description": {
                "type": "string",
                "description": "Description of the profile property"
              },
              "type": {
                "type": "string",
                "enum": [
                  "boolean",
                  "numeric",
                  "freetext",
                  "freetext_multiline",
                  "list_single_option",
                  "list_multi_option",
                  "date",
                  "time",
                  "datetime",
                  "upload"
                ],
                "description": "Type of content of the profile property"
              },
              "numeric_unit": {
                "type": "string",
                "description": "Unit in which a profile property of type numeric is expressed"
              },
              "value_boolean": {
                "type": "boolean",
                "description": "Value of the profile property.  Filled for type = boolean"
              },
              "value_string": {
                "type": "string",
                "description": "Value of the profile property.  Filled for type = freetext, freetext_multiline or list_single_option"
              },
              "value_list_multi": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Filled for type = list_multi_option"
              },
              "value_date": {
                "type": "string",
                "description": "Value of the profile property. Filled for type = date according to RFC 3339"
              },
              "value_time": {
                "type": "string",
                "description": "Value of the profile property. Filled for type = time according to RFC 3339"
              },
              "value_datetime": {
                "type": "string",
                "description": "Value of the profile property. Filled for type = datetime according to RFC 3339"
              },
              "value_numeric": {
                "type": "number",
                "description": "Value of the profile property.  Filled for type = numeric"
              },
              "value_upload_url": {
                "type": "string",
                "description": "Value (URL) of the profile property. Filled for type = upload"
              },
              "comment": {
                "type": "string",
                "description": "Comment concerning the value of the profile property"
              },
              "expiration_date": {
                "type": "string",
                "description": "Date the value of the profile property expires according to RFC 3339"
              },
              "piece_of_evidence": {
                "type": "string",
                "description": "Piece of evidence (URL) for the value of the profile property"
              }
            }
          }
        }
      },
      "required": [
        "first_name",
        "last_name",
        "prefix",
        "beeple_id",
        "language",
        "primary_department_id",
        "primary_manager_id"
      ]
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "external_id": "P77881"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "external_id": {
      "type": "string",
      "description": "The identification that was attributed to the created collaborator"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "translations": [
        {
          "language": "EN",
          "error": "Detailed error message"
        }
      ],
      "code": "A001"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "translations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "language": {
                  "type": "string",
                  "description": "The ISO language code"
                },
                "error": {
                  "type": "string",
                  "description": "A detailed error message"
                }
              }
            }
          },
          "code": {
            "type": "string",
            "description": "An optional error code. Beeple will just use this\n\nfor detailed reporting, but will never interpret this value."
          }
        }
      }
    }
  }
}

One Collaborator

Collaborator updated
PATCH/collaborators/{beeple_id}

This message will be sent every time an already linked collaborator is updated within Beeple.

It can reply with a 400 status code when the user could not be updated. The response should then contain error messages about the issues. Beeple will not retry sending the same request in this case.

Other errors (especially in the 500 range) Beeple will actually retry sending the request a few times at certain intervals.

Example URI

PATCH /collaborators/1454
URI Parameters
HideShow
beeple_id
string (required) Example: 1454

The Beeple ID of the collaborator

Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Body
{
  "company": {
    "name": "My company",
    "beeple_id": "273e949a-bb41-4f36-9526-d1d0a8043c91",
    "enterprise_number": "0101010101",
    "payroll_service_id": "5"
  },
  "collaborator": {
    "first_name": "John",
    "last_name": "Doe",
    "prefix": "De",
    "beeple_id": 2403,
    "birth_date": "1995-05-07",
    "birth_city": "Antwerpen",
    "birth_country": "BE",
    "gender": "male",
    "language": "en",
    "nationality": "BE",
    "national_registration_numbers": [
      {
        "country": "BE",
        "number": "95.05.07-997.47"
      }
    ],
    "social_statute": "Arbeider",
    "social_statute_code": "career_pause",
    "home_address": {
      "street1": "Dorpstraat 1",
      "street2": "Bus 1",
      "zip": "2018",
      "city": "Antwerpen",
      "administrative_area_level_1": "Hello, world!",
      "administrative_area_level_2": "Hello, world!",
      "administrative_area_level_3": "Hello, world!",
      "administrative_area_level_4": "Hello, world!",
      "administrative_area_level_5": "Hello, world!",
      "country": "BE"
    },
    "bank_account": {
      "iban": "BE68539007547034",
      "bic": "HBKABE22"
    },
    "blocked": false,
    "blocked_reason": "nothing to say",
    "contact": {
      "email": "john.doe@example.org",
      "mobile": "+32498525251"
    },
    "departments": [
      {
        "id": 2403,
        "name": "Accounting"
      }
    ],
    "primary_department_id": 7487,
    "primary_manager_id": 122,
    "profile_properties": [
      {
        "group": "Legal information",
        "profile_property_id": 1888,
        "name": "Marital status",
        "description": "Here you can enter your official marital status",
        "type": "boolean",
        "numeric_unit": "km",
        "value_boolean": true,
        "value_string": "Married",
        "value_list_multi": [
          "english"
        ],
        "value_date": "2017-05-08",
        "value_time": "17:00:00.000+02:00",
        "value_datetime": "2017-05-08T17:00:00.000+02:00",
        "value_numeric": 23.5,
        "value_upload_url": "https://planning.tenant.be/api/v1/uploads/volunteers/volunteers_profile_property/upload_collaborator/5916/uploaded_file.docx",
        "comment": "Since 15/5/1995",
        "expiration_date": "2017-05-08",
        "piece_of_evidence": "https://planning.tenant.be/api/v1/uploads/volunteers/volunteers_profile_property/documented_proof_verified/43413/piece_of_evidence_file.docx"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "company": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the company (tenant). Can change and is mainly for displaying purposes"
        },
        "beeple_id": {
          "type": "string",
          "description": "The ID of the Beeple Tenant (a UUID). Will never change for a given tenant."
        },
        "enterprise_number": {
          "type": "string",
          "description": "Enterprise number of this company"
        },
        "payroll_service_id": {
          "type": "string",
          "description": "A payroll service ID."
        }
      },
      "required": [
        "name",
        "beeple_id"
      ],
      "description": "Company that is sending this information."
    },
    "collaborator": {
      "type": "object",
      "properties": {
        "first_name": {
          "type": "string",
          "description": "First name"
        },
        "last_name": {
          "type": "string",
          "description": "Last name"
        },
        "prefix": {
          "type": "string",
          "description": "Last name prefix, this is what appears on the screen of the web application as \"infix\"; for example John De Doe"
        },
        "beeple_id": {
          "type": "number",
          "description": "Identification number within Beeple"
        },
        "birth_date": {
          "type": "string",
          "description": "Birth date according RFC 3339"
        },
        "birth_city": {
          "type": "string",
          "description": "Birth city"
        },
        "birth_country": {
          "type": "string",
          "description": "Birth country according to ISO 3166-1 alpha-2"
        },
        "gender": {
          "type": "string",
          "enum": [
            "male",
            "female"
          ],
          "description": "Gender"
        },
        "language": {
          "type": "string",
          "description": "Language in which to communicate with the collaborator according to ISO 639-1"
        },
        "nationality": {
          "type": "string",
          "description": "According to ISO 3166-1 alpha-2"
        },
        "national_registration_numbers": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "country": {
                "type": "string",
                "description": "Country for which the number is valid according to ISO 3166-1 alpha-2"
              },
              "number": {
                "type": "string"
              }
            }
          }
        },
        "social_statute": {
          "type": "string",
          "description": "The social statute"
        },
        "social_statute_code": {
          "type": "string",
          "enum": [
            "career_pause",
            "disabled_entrepreneur",
            "early_retired",
            "entrepreneur",
            "flexijobs",
            "functionary",
            "incapacitated",
            "living_wager",
            "retired",
            "student",
            "unemployed",
            "unemployed_waiting_period",
            "unknown",
            "working_class",
            "working_class_blue_collar",
            "work_student"
          ],
          "description": "The social statute"
        },
        "home_address": {
          "type": "object",
          "properties": {
            "street1": {
              "type": "string",
              "description": "Street + house number"
            },
            "street2": {
              "type": "string",
              "description": "Extension of street1"
            },
            "zip": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "administrative_area_level_1": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "administrative_area_level_2": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "administrative_area_level_3": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "administrative_area_level_4": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "administrative_area_level_5": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "country": {
              "type": "string",
              "description": "According to ISO 3166-1 alpha-2"
            }
          }
        },
        "bank_account": {
          "type": "object",
          "properties": {
            "iban": {
              "type": "string"
            },
            "bic": {
              "type": "string"
            }
          }
        },
        "blocked": {
          "type": "boolean",
          "description": "Indicates if the user is blocked"
        },
        "blocked_reason": {
          "type": "string",
          "description": "A comment posted during block or unblock"
        },
        "contact": {
          "type": "object",
          "properties": {
            "email": {
              "type": "string"
            },
            "mobile": {
              "type": "string"
            }
          },
          "required": [
            "email"
          ]
        },
        "departments": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "Identification number of the department within Beeple"
              },
              "name": {
                "type": "string",
                "description": "Name of the department"
              }
            },
            "required": [
              "id"
            ]
          },
          "description": "List of departments the collaborator belongs to"
        },
        "primary_department_id": {
          "type": "number",
          "description": "The ID of the collaborator's primary department. Will be the id of one of the collaborator's departments"
        },
        "primary_manager_id": {
          "type": "number",
          "description": "The ID of the collaborator's manager. Must be a collaborator that is an admin and has access rights to approve availabilities."
        },
        "profile_properties": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "group": {
                "type": "string",
                "description": "Group of profile properties"
              },
              "profile_property_id": {
                "type": "number",
                "description": "Id of the profile property"
              },
              "name": {
                "type": "string",
                "description": "Name of the profile property"
              },
              "description": {
                "type": "string",
                "description": "Description of the profile property"
              },
              "type": {
                "type": "string",
                "enum": [
                  "boolean",
                  "numeric",
                  "freetext",
                  "freetext_multiline",
                  "list_single_option",
                  "list_multi_option",
                  "date",
                  "time",
                  "datetime",
                  "upload"
                ],
                "description": "Type of content of the profile property"
              },
              "numeric_unit": {
                "type": "string",
                "description": "Unit in which a profile property of type numeric is expressed"
              },
              "value_boolean": {
                "type": "boolean",
                "description": "Value of the profile property.  Filled for type = boolean"
              },
              "value_string": {
                "type": "string",
                "description": "Value of the profile property.  Filled for type = freetext, freetext_multiline or list_single_option"
              },
              "value_list_multi": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Filled for type = list_multi_option"
              },
              "value_date": {
                "type": "string",
                "description": "Value of the profile property. Filled for type = date according to RFC 3339"
              },
              "value_time": {
                "type": "string",
                "description": "Value of the profile property. Filled for type = time according to RFC 3339"
              },
              "value_datetime": {
                "type": "string",
                "description": "Value of the profile property. Filled for type = datetime according to RFC 3339"
              },
              "value_numeric": {
                "type": "number",
                "description": "Value of the profile property.  Filled for type = numeric"
              },
              "value_upload_url": {
                "type": "string",
                "description": "Value (URL) of the profile property. Filled for type = upload"
              },
              "comment": {
                "type": "string",
                "description": "Comment concerning the value of the profile property"
              },
              "expiration_date": {
                "type": "string",
                "description": "Date the value of the profile property expires according to RFC 3339"
              },
              "piece_of_evidence": {
                "type": "string",
                "description": "Piece of evidence (URL) for the value of the profile property"
              }
            }
          }
        }
      },
      "required": [
        "first_name",
        "last_name",
        "prefix",
        "beeple_id",
        "language",
        "primary_department_id",
        "primary_manager_id"
      ]
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "translations": [
        {
          "language": "EN",
          "error": "Detailed error message"
        }
      ],
      "code": "A001"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "translations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "language": {
                  "type": "string",
                  "description": "The ISO language code"
                },
                "error": {
                  "type": "string",
                  "description": "A detailed error message"
                }
              }
            }
          },
          "code": {
            "type": "string",
            "description": "An optional error code. Beeple will just use this\n\nfor detailed reporting, but will never interpret this value."
          }
        }
      }
    }
  }
}

Collaborator unlinked
DELETE/collaborators/{beeple_id}?company_id={company_id}

This request will be sent when either the collaborator is deleted in Beeple or when the link between the collaborator and the payroll gets removed.

After this message no more updates will come through for this collaborator

It is up to the implementation to decide what to do with this information, it is however not allowed to not allow this operation.

Example URI

DELETE /collaborators/1454?company_id=ddde1555-9bb6-4180-91f4-db063f54c9c8
URI Parameters
HideShow
beeple_id
string (required) Example: 1454

The Beeple ID of the collaborator

company_id
string (required) Example: ddde1555-9bb6-4180-91f4-db063f54c9c8

The ID of the tenant. A UUID which will not change.

Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Response  200
HideShow
Headers
Content-Type: application/json
Response  204
HideShow
Headers
Content-Type: application/json

Collaborator management

It is possible to register collaborators via the 3rd party. This is a call from the 3rd party to a beeple endpoint.

Register a collaborator
POST/api/v1/incoming/collaborators

Example URI

POST /api/v1/incoming/collaborators
Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Body
{
  "company": {
    "name": "My company",
    "beeple_id": "273e949a-bb41-4f36-9526-d1d0a8043c91",
    "enterprise_number": "0101010101",
    "payroll_service_id": "5"
  },
  "collaborator": {
    "first_name": "John",
    "last_name": "Doe",
    "prefix": "De",
    "beeple_id": 2403,
    "birth_date": "1995-05-07",
    "birth_city": "Antwerpen",
    "birth_country": "BE",
    "gender": "male",
    "language": "en",
    "nationality": "BE",
    "national_registration_numbers": [
      {
        "country": "BE",
        "number": "95.05.07-997.47"
      }
    ],
    "social_statute": "Arbeider",
    "social_statute_code": "career_pause",
    "home_address": {
      "street1": "Dorpstraat 1",
      "street2": "Bus 1",
      "zip": "2018",
      "city": "Antwerpen",
      "administrative_area_level_1": "Hello, world!",
      "administrative_area_level_2": "Hello, world!",
      "administrative_area_level_3": "Hello, world!",
      "administrative_area_level_4": "Hello, world!",
      "administrative_area_level_5": "Hello, world!",
      "country": "BE"
    },
    "bank_account": {
      "iban": "BE68539007547034",
      "bic": "HBKABE22"
    },
    "blocked": false,
    "blocked_reason": "nothing to say",
    "contact": {
      "email": "john.doe@example.org",
      "mobile": "+32498525251"
    },
    "departments": [
      {
        "id": 2403,
        "name": "Accounting"
      }
    ],
    "primary_department_id": 7487,
    "primary_manager_id": 122,
    "profile_properties": [
      {
        "group": "Legal information",
        "profile_property_id": 1888,
        "name": "Marital status",
        "description": "Here you can enter your official marital status",
        "type": "boolean",
        "numeric_unit": "km",
        "value_boolean": true,
        "value_string": "Married",
        "value_list_multi": [
          "english"
        ],
        "value_date": "2017-05-08",
        "value_time": "17:00:00.000+02:00",
        "value_datetime": "2017-05-08T17:00:00.000+02:00",
        "value_numeric": 23.5,
        "value_upload_url": "https://planning.tenant.be/api/v1/uploads/volunteers/volunteers_profile_property/upload_collaborator/5916/uploaded_file.docx",
        "comment": "Since 15/5/1995",
        "expiration_date": "2017-05-08",
        "piece_of_evidence": "https://planning.tenant.be/api/v1/uploads/volunteers/volunteers_profile_property/documented_proof_verified/43413/piece_of_evidence_file.docx"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "company": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the company (tenant). Can change and is mainly for displaying purposes"
        },
        "beeple_id": {
          "type": "string",
          "description": "The ID of the Beeple Tenant (a UUID). Will never change for a given tenant."
        },
        "enterprise_number": {
          "type": "string",
          "description": "Enterprise number of this company"
        },
        "payroll_service_id": {
          "type": "string",
          "description": "A payroll service ID."
        }
      },
      "required": [
        "name",
        "beeple_id"
      ],
      "description": "Company that is sending this information."
    },
    "collaborator": {
      "type": "object",
      "properties": {
        "first_name": {
          "type": "string",
          "description": "First name"
        },
        "last_name": {
          "type": "string",
          "description": "Last name"
        },
        "prefix": {
          "type": "string",
          "description": "Last name prefix, this is what appears on the screen of the web application as \"infix\"; for example John De Doe"
        },
        "beeple_id": {
          "type": "number",
          "description": "Identification number within Beeple"
        },
        "birth_date": {
          "type": "string",
          "description": "Birth date according RFC 3339"
        },
        "birth_city": {
          "type": "string",
          "description": "Birth city"
        },
        "birth_country": {
          "type": "string",
          "description": "Birth country according to ISO 3166-1 alpha-2"
        },
        "gender": {
          "type": "string",
          "enum": [
            "male",
            "female"
          ],
          "description": "Gender"
        },
        "language": {
          "type": "string",
          "description": "Language in which to communicate with the collaborator according to ISO 639-1"
        },
        "nationality": {
          "type": "string",
          "description": "According to ISO 3166-1 alpha-2"
        },
        "national_registration_numbers": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "country": {
                "type": "string",
                "description": "Country for which the number is valid according to ISO 3166-1 alpha-2"
              },
              "number": {
                "type": "string"
              }
            }
          }
        },
        "social_statute": {
          "type": "string",
          "description": "The social statute"
        },
        "social_statute_code": {
          "type": "string",
          "enum": [
            "career_pause",
            "disabled_entrepreneur",
            "early_retired",
            "entrepreneur",
            "flexijobs",
            "functionary",
            "incapacitated",
            "living_wager",
            "retired",
            "student",
            "unemployed",
            "unemployed_waiting_period",
            "unknown",
            "working_class",
            "working_class_blue_collar",
            "work_student"
          ],
          "description": "The social statute"
        },
        "home_address": {
          "type": "object",
          "properties": {
            "street1": {
              "type": "string",
              "description": "Street + house number"
            },
            "street2": {
              "type": "string",
              "description": "Extension of street1"
            },
            "zip": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "administrative_area_level_1": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "administrative_area_level_2": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "administrative_area_level_3": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "administrative_area_level_4": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "administrative_area_level_5": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "country": {
              "type": "string",
              "description": "According to ISO 3166-1 alpha-2"
            }
          }
        },
        "bank_account": {
          "type": "object",
          "properties": {
            "iban": {
              "type": "string"
            },
            "bic": {
              "type": "string"
            }
          }
        },
        "blocked": {
          "type": "boolean",
          "description": "Indicates if the user is blocked"
        },
        "blocked_reason": {
          "type": "string",
          "description": "A comment posted during block or unblock"
        },
        "contact": {
          "type": "object",
          "properties": {
            "email": {
              "type": "string"
            },
            "mobile": {
              "type": "string"
            }
          },
          "required": [
            "email"
          ]
        },
        "departments": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "Identification number of the department within Beeple"
              },
              "name": {
                "type": "string",
                "description": "Name of the department"
              }
            },
            "required": [
              "id"
            ]
          },
          "description": "List of departments the collaborator belongs to"
        },
        "primary_department_id": {
          "type": "number",
          "description": "The ID of the collaborator's primary department. Will be the id of one of the collaborator's departments"
        },
        "primary_manager_id": {
          "type": "number",
          "description": "The ID of the collaborator's manager. Must be a collaborator that is an admin and has access rights to approve availabilities."
        },
        "profile_properties": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "group": {
                "type": "string",
                "description": "Group of profile properties"
              },
              "profile_property_id": {
                "type": "number",
                "description": "Id of the profile property"
              },
              "name": {
                "type": "string",
                "description": "Name of the profile property"
              },
              "description": {
                "type": "string",
                "description": "Description of the profile property"
              },
              "type": {
                "type": "string",
                "enum": [
                  "boolean",
                  "numeric",
                  "freetext",
                  "freetext_multiline",
                  "list_single_option",
                  "list_multi_option",
                  "date",
                  "time",
                  "datetime",
                  "upload"
                ],
                "description": "Type of content of the profile property"
              },
              "numeric_unit": {
                "type": "string",
                "description": "Unit in which a profile property of type numeric is expressed"
              },
              "value_boolean": {
                "type": "boolean",
                "description": "Value of the profile property.  Filled for type = boolean"
              },
              "value_string": {
                "type": "string",
                "description": "Value of the profile property.  Filled for type = freetext, freetext_multiline or list_single_option"
              },
              "value_list_multi": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Filled for type = list_multi_option"
              },
              "value_date": {
                "type": "string",
                "description": "Value of the profile property. Filled for type = date according to RFC 3339"
              },
              "value_time": {
                "type": "string",
                "description": "Value of the profile property. Filled for type = time according to RFC 3339"
              },
              "value_datetime": {
                "type": "string",
                "description": "Value of the profile property. Filled for type = datetime according to RFC 3339"
              },
              "value_numeric": {
                "type": "number",
                "description": "Value of the profile property.  Filled for type = numeric"
              },
              "value_upload_url": {
                "type": "string",
                "description": "Value (URL) of the profile property. Filled for type = upload"
              },
              "comment": {
                "type": "string",
                "description": "Comment concerning the value of the profile property"
              },
              "expiration_date": {
                "type": "string",
                "description": "Date the value of the profile property expires according to RFC 3339"
              },
              "piece_of_evidence": {
                "type": "string",
                "description": "Piece of evidence (URL) for the value of the profile property"
              }
            }
          }
        }
      },
      "required": [
        "first_name",
        "last_name",
        "prefix",
        "beeple_id",
        "language",
        "primary_department_id",
        "primary_manager_id"
      ]
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json

Contract requests

List of Contracts

Request contract
POST/contracts

For each shift of a confirmed enrolment in Beeple, Beeple sends a request for the creation of a contract to the subscribed 3rd party system. Beeple expects a response with

  • if the contract was not created: the error code

  • if the contract was created: the contract number attributed in the 3rd party system.

As in Beeple contracts are not updated but deleted and recreated, Beeple also sends the same request to create a contract for each change that possibly impacts a contract, immediately after a request to cancel the concerned contract. E.g. if the display color of a project changes in Beeple, this will not result in a request to cancel and to recreate the contract, but if the planned hours change, it will.

There are 2 possible responses. Either the contract is accepted synchronously and the system must respond with a 200 success code, or the contract is accepted asynchrounously and the system must respond with status code 202. In both cases later state changes can be sent with callbacks to the Beeple system.

Possible states of a (non cancelled) contract are

  • pending : The contract is not created yet, no validation has happened

  • accepted : The contract is not created yet, but the assumption (based on validations) is made that creating will succeed at one point. It is still possible that a denied happens but this should be an exceptional flow.

  • created : The contract is created, and all legal requirements are fulfilled. This is a final state.

  • denied : The contract could not be created, and unless changes are made to the request it will also never be completed. This is a final state.

Example URI

POST /contracts
Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Body
{
  "company": {
    "name": "My company",
    "beeple_id": "273e949a-bb41-4f36-9526-d1d0a8043c91",
    "enterprise_number": "0101010101",
    "payroll_service_id": "5"
  },
  "contract": {
    "beeple_id": "87643",
    "created_at": "2017-04-01T10:00:00.000+02:00",
    "team_registration_id": "652",
    "shift_id": "891",
    "branch_id": "example@example.org",
    "collaborator": {
      "beeple_id": 2403,
      "external_id": "P77881"
    },
    "project": "Beeple project",
    "project_id": "789",
    "project_details": {
      "id": "787",
      "department_id": "44554",
      "client_name": "Client Org",
      "client_id": "4242",
      "custom_planning_fields": [
        {
          "property_id": "45522",
          "group_name": "A Group Name",
          "name": "Some Name",
          "description": "A Description",
          "type": "boolean",
          "numeric_unit": "km",
          "value_string": "Example Value",
          "value_boolean": true,
          "value_list_single": "Example Value",
          "value_list_multi": [
            "Example Value"
          ],
          "value_upload_url": "Example Value",
          "value_date": "Example Value",
          "value_datetime": "Example Value",
          "value_time": "Example Value",
          "value_numeric": 23.5
        }
      ]
    },
    "subproject": "Beeple subproject",
    "subproject_id": "456",
    "subproject_details": {
      "id": "983",
      "custom_planning_fields": [
        {
          "property_id": "45522",
          "group_name": "A Group Name",
          "name": "Some Name",
          "description": "A Description",
          "type": "boolean",
          "numeric_unit": "km",
          "value_string": "Example Value",
          "value_boolean": true,
          "value_list_single": "Example Value",
          "value_list_multi": [
            "Example Value"
          ],
          "value_upload_url": "Example Value",
          "value_date": "Example Value",
          "value_datetime": "Example Value",
          "value_time": "Example Value",
          "value_numeric": 23.5
        }
      ]
    },
    "team": "Beeple team",
    "team_id": "123",
    "team_details": {
      "id": "4523",
      "custom_planning_fields": [
        {
          "property_id": "45522",
          "group_name": "A Group Name",
          "name": "Some Name",
          "description": "A Description",
          "type": "boolean",
          "numeric_unit": "km",
          "value_string": "Example Value",
          "value_boolean": true,
          "value_list_single": "Example Value",
          "value_list_multi": [
            "Example Value"
          ],
          "value_upload_url": "Example Value",
          "value_date": "Example Value",
          "value_datetime": "Example Value",
          "value_time": "Example Value",
          "value_numeric": 23.5
        }
      ]
    },
    "department": "Department",
    "email_responsible_for_hours": "example@example.org",
    "planned_hours": {
      "start": "2017-04-01T10:00:00.000+02:00",
      "end": "2017-04-01T19:00:00.000+02:00",
      "duration": "09:00",
      "break_duration": "01:00",
      "work_duration": "08:00"
    },
    "work_station_address": {
      "street1": "Dorpstraat 1",
      "street2": "Bus 1",
      "zip": "2018",
      "city": "Antwerpen",
      "administrative_area_level_1": "Hello, world!",
      "administrative_area_level_2": "Hello, world!",
      "administrative_area_level_3": "Hello, world!",
      "administrative_area_level_4": "Hello, world!",
      "administrative_area_level_5": "Hello, world!",
      "country": "BE",
      "addition": "At the entrance"
    },
    "work_station_address_id": "456",
    "function": "Waiter",
    "function_id": "901",
    "function_details": {
      "id": "4511",
      "name_i18n_attributes": {
        "language": "en",
        "name": "Some name"
      },
      "description_i18n_attributes": {
        "language": "en",
        "description": "Some description"
      }
    },
    "contract_type": "interim",
    "be_work_statute": "arbeider",
    "wages": {
      "per_hour": 11.25,
      "per_day": 75.25,
      "per_team": 155.25
    },
    "commute_distance_in_km": 75.53,
    "enrolment_properties": [
      {
        "property_id": "101",
        "group": "Tools available",
        "name": "Car",
        "description": "Do you have a car available for this enrolment?",
        "type": "boolean",
        "numeric_unit": "km",
        "value_boolean": true,
        "value_string": "Married",
        "value_list_multi": [
          "English"
        ],
        "value_date": "2017-05-08",
        "value_time": "17:00:00.000+02:00",
        "value_datetime": "2017-05-08T17:00:00.000+02:00",
        "value_numeric": 23.5,
        "value_upload_url": "https://planning.tenant.be/api/v1/uploads/volunteers/volunteers_enrolment_property/upload_collaborator/5916/uploaded_file.docx",
        "comment": "It is my husband's car.",
        "piece_of_evidence": "https://planning.tenant.be/api/v1/uploads/volunteers/volunteers_enrolment_property/documented_proof_verified/43413/piece_of_evidence_file.docx"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "company": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the company (tenant). Can change and is mainly for displaying purposes"
        },
        "beeple_id": {
          "type": "string",
          "description": "The ID of the Beeple Tenant (a UUID). Will never change for a given tenant."
        },
        "enterprise_number": {
          "type": "string",
          "description": "Enterprise number of this company"
        },
        "payroll_service_id": {
          "type": "string",
          "description": "A payroll service ID."
        }
      },
      "required": [
        "name",
        "beeple_id"
      ],
      "description": "Company that is sending this information."
    },
    "contract": {
      "type": "object",
      "properties": {
        "beeple_id": {
          "type": "string",
          "description": "Identification number within Beeple"
        },
        "created_at": {
          "type": "string",
          "description": "When the contract was created in Beeple"
        },
        "team_registration_id": {
          "type": "string",
          "description": "ID of the enrolment in Beeple"
        },
        "shift_id": {
          "type": "string",
          "description": "ID of the shift in Beeple"
        },
        "branch_id": {
          "type": "string",
          "description": "ID of the payroll brnach. Note the ID is currently the email-address of the receiver"
        },
        "collaborator": {
          "type": "object",
          "properties": {
            "beeple_id": {
              "type": "number",
              "description": "Identification number within Beeple"
            },
            "external_id": {
              "type": "string",
              "description": "Identification in 3rd party system"
            }
          },
          "required": [
            "beeple_id",
            "external_id"
          ],
          "description": "Collaborator for whom worked hours are approved"
        },
        "project": {
          "type": "string",
          "description": "Name of the project in Beeple"
        },
        "project_id": {
          "type": "string",
          "description": "ID of the project"
        },
        "project_details": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "ID of the project"
            },
            "department_id": {
              "type": "string",
              "description": "ID of the department (if any)"
            },
            "client_name": {
              "type": "string",
              "description": "The name of the client (if any)"
            },
            "client_id": {
              "type": "string",
              "description": "The ID of the client (if any)"
            },
            "custom_planning_fields": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "property_id": {
                    "type": "string",
                    "description": "The ID of the custom property"
                  },
                  "group_name": {
                    "type": "string",
                    "description": "The human name of the group of properties"
                  },
                  "name": {
                    "type": "string",
                    "description": "The human name of the profile property"
                  },
                  "description": {
                    "type": "string",
                    "description": "The human description of the profile property"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "boolean",
                      "numeric",
                      "freetext",
                      "freetext_multiline",
                      "list_single_option",
                      "list_multi_option",
                      "date",
                      "time",
                      "datetime",
                      "upload"
                    ],
                    "description": "The type of custom property"
                  },
                  "numeric_unit": {
                    "type": "string",
                    "description": "A (human) numeric unit"
                  },
                  "value_string": {
                    "type": "string",
                    "description": "The string value of the property (also for multiline)"
                  },
                  "value_boolean": {
                    "type": "boolean",
                    "description": "The boolean value"
                  },
                  "value_list_single": {
                    "type": "string",
                    "description": "The slug value of the selected list"
                  },
                  "value_list_multi": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The selected values (slugs) of a multiselect"
                  },
                  "value_upload_url": {
                    "type": "string",
                    "description": "The (only temporary valud) URL of the upload"
                  },
                  "value_date": {
                    "type": "string",
                    "description": "The date of the value according to RFC 3339"
                  },
                  "value_datetime": {
                    "type": "string",
                    "description": "The datetime of the value  according to RFC 3339"
                  },
                  "value_time": {
                    "type": "string",
                    "description": "The time of the value in format HH:MM"
                  },
                  "value_numeric": {
                    "type": "number",
                    "description": "The numeric value of the property"
                  }
                }
              },
              "description": "A list of all planning fields on the project"
            }
          },
          "description": "Details of the project"
        },
        "subproject": {
          "type": "string",
          "description": "Name of the subproject in Beeple"
        },
        "subproject_id": {
          "type": "string",
          "description": "ID of the subproject"
        },
        "subproject_details": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "ID of the subproject"
            },
            "custom_planning_fields": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "property_id": {
                    "type": "string",
                    "description": "The ID of the custom property"
                  },
                  "group_name": {
                    "type": "string",
                    "description": "The human name of the group of properties"
                  },
                  "name": {
                    "type": "string",
                    "description": "The human name of the profile property"
                  },
                  "description": {
                    "type": "string",
                    "description": "The human description of the profile property"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "boolean",
                      "numeric",
                      "freetext",
                      "freetext_multiline",
                      "list_single_option",
                      "list_multi_option",
                      "date",
                      "time",
                      "datetime",
                      "upload"
                    ],
                    "description": "The type of custom property"
                  },
                  "numeric_unit": {
                    "type": "string",
                    "description": "A (human) numeric unit"
                  },
                  "value_string": {
                    "type": "string",
                    "description": "The string value of the property (also for multiline)"
                  },
                  "value_boolean": {
                    "type": "boolean",
                    "description": "The boolean value"
                  },
                  "value_list_single": {
                    "type": "string",
                    "description": "The slug value of the selected list"
                  },
                  "value_list_multi": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The selected values (slugs) of a multiselect"
                  },
                  "value_upload_url": {
                    "type": "string",
                    "description": "The (only temporary valud) URL of the upload"
                  },
                  "value_date": {
                    "type": "string",
                    "description": "The date of the value according to RFC 3339"
                  },
                  "value_datetime": {
                    "type": "string",
                    "description": "The datetime of the value  according to RFC 3339"
                  },
                  "value_time": {
                    "type": "string",
                    "description": "The time of the value in format HH:MM"
                  },
                  "value_numeric": {
                    "type": "number",
                    "description": "The numeric value of the property"
                  }
                }
              },
              "description": "A list of all planning fields on the subproject"
            }
          },
          "description": "Details of the subproject"
        },
        "team": {
          "type": "string",
          "description": "Name of the team in Beeple"
        },
        "team_id": {
          "type": "string",
          "description": "ID of the team"
        },
        "team_details": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "ID of the team"
            },
            "custom_planning_fields": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "property_id": {
                    "type": "string",
                    "description": "The ID of the custom property"
                  },
                  "group_name": {
                    "type": "string",
                    "description": "The human name of the group of properties"
                  },
                  "name": {
                    "type": "string",
                    "description": "The human name of the profile property"
                  },
                  "description": {
                    "type": "string",
                    "description": "The human description of the profile property"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "boolean",
                      "numeric",
                      "freetext",
                      "freetext_multiline",
                      "list_single_option",
                      "list_multi_option",
                      "date",
                      "time",
                      "datetime",
                      "upload"
                    ],
                    "description": "The type of custom property"
                  },
                  "numeric_unit": {
                    "type": "string",
                    "description": "A (human) numeric unit"
                  },
                  "value_string": {
                    "type": "string",
                    "description": "The string value of the property (also for multiline)"
                  },
                  "value_boolean": {
                    "type": "boolean",
                    "description": "The boolean value"
                  },
                  "value_list_single": {
                    "type": "string",
                    "description": "The slug value of the selected list"
                  },
                  "value_list_multi": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The selected values (slugs) of a multiselect"
                  },
                  "value_upload_url": {
                    "type": "string",
                    "description": "The (only temporary valud) URL of the upload"
                  },
                  "value_date": {
                    "type": "string",
                    "description": "The date of the value according to RFC 3339"
                  },
                  "value_datetime": {
                    "type": "string",
                    "description": "The datetime of the value  according to RFC 3339"
                  },
                  "value_time": {
                    "type": "string",
                    "description": "The time of the value in format HH:MM"
                  },
                  "value_numeric": {
                    "type": "number",
                    "description": "The numeric value of the property"
                  }
                }
              },
              "description": "A list of all planning fields on the team"
            }
          },
          "description": "Details of the subproject"
        },
        "department": {
          "type": "string",
          "description": "Name of the department in Beeple"
        },
        "email_responsible_for_hours": {
          "type": "string",
          "description": "Emailaddress of the collaborator in Beeple responsible for passing hours"
        },
        "planned_hours": {
          "type": "object",
          "properties": {
            "start": {
              "type": "string",
              "description": "When the collaborator had to start working for the reported shift according RFC 3339"
            },
            "end": {
              "type": "string",
              "description": "When the collaborator had to stop working for the reported shift according RFC 3339"
            },
            "duration": {
              "type": "string",
              "description": "How long the collaborator was planned to be present in the reported shift according RFC 3339"
            },
            "break_duration": {
              "type": "string",
              "description": "How long the collaborator was planned not to work in the reported shift according RFC 3339"
            },
            "work_duration": {
              "type": "string",
              "description": "How long the collaborator was planned to work in the reported shift according RFC 3339"
            }
          },
          "required": [
            "start",
            "end",
            "duration",
            "break_duration",
            "work_duration"
          ]
        },
        "work_station_address": {
          "type": "object",
          "properties": {
            "street1": {
              "type": "string",
              "description": "Street + house number"
            },
            "street2": {
              "type": "string",
              "description": "Extension of street1"
            },
            "zip": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "administrative_area_level_1": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "administrative_area_level_2": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "administrative_area_level_3": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "administrative_area_level_4": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "administrative_area_level_5": {
              "type": "string",
              "description": "An extra administrative level, depends per country / tenant what this means"
            },
            "country": {
              "type": "string",
              "description": "According to ISO 3166-1 alpha-2"
            },
            "addition": {
              "type": "string",
              "description": "Specific location where the collaborator was planed to work"
            }
          },
          "description": "Where the collaborator was planned to work"
        },
        "work_station_address_id": {
          "type": "string",
          "description": "ID of the work station address"
        },
        "function": {
          "type": "string",
          "description": "Function that the collaborator was planned to excute"
        },
        "function_id": {
          "type": "string",
          "description": "The ID of the function"
        },
        "function_details": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "ID of the function"
            },
            "name_i18n_attributes": {
              "type": "object",
              "properties": {
                "language": {
                  "type": "string",
                  "description": "[ISO 639-1 code](https://en.wikipedia.org/wiki/ISO_639-1) of the language used in `name`."
                },
                "name": {
                  "type": "string",
                  "description": "the name of the given attribute expressed in the specific `language`"
                }
              },
              "required": [
                "language",
                "name"
              ]
            },
            "description_i18n_attributes": {
              "type": "object",
              "properties": {
                "language": {
                  "type": "string",
                  "description": "[ISO 639-1 code](https://en.wikipedia.org/wiki/ISO_639-1) of the language used in `description`"
                },
                "description": {
                  "type": "string",
                  "description": "the description of the given attribute expressed in the specific `language`"
                }
              },
              "required": [
                "language",
                "description"
              ]
            }
          },
          "required": [
            "name_i18n_attributes"
          ]
        },
        "contract_type": {
          "type": "string",
          "enum": [
            "interim",
            "freelancer",
            "intern",
            "contractual",
            "volunteer"
          ],
          "description": "The type of contract the needs to be created"
        },
        "be_work_statute": {
          "type": "string",
          "enum": [
            "arbeider",
            "bediende"
          ],
          "description": "Type type of work type for Belgium contracts"
        },
        "commute_distance_in_km": {
          "type": "number",
          "description": "Distance between collaborator's home address and either the planned work station address or planned check-in address in kiometers"
        },
        "enrolment_properties": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "property_id": {
                "type": "string",
                "description": "The ID of the enrolment property"
              },
              "group": {
                "type": "string",
                "description": "Group of enrolment properties"
              },
              "name": {
                "type": "string",
                "description": "Name of the enrolment property"
              },
              "description": {
                "type": "string",
                "description": "Description of the enrolment property"
              },
              "type": {
                "type": "string",
                "enum": [
                  "boolean",
                  "numeric",
                  "freetext",
                  "freetext_multiline",
                  "list_single_option",
                  "list_multi_option",
                  "date",
                  "time",
                  "datetime",
                  "upload"
                ],
                "description": "Type of content of the enrolment property"
              },
              "numeric_unit": {
                "type": "string",
                "description": "Unit in which a enrolment property of type numeric is expressed"
              },
              "value_boolean": {
                "type": "boolean",
                "description": "Value of the enrolment property.  Filled for type = boolean"
              },
              "value_string": {
                "type": "string",
                "description": "Value of the enrolment property.  Filled for type = freetext, freetext_multiline or list_single_option"
              },
              "value_list_multi": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Filled for type = list_multi_option"
              },
              "value_date": {
                "type": "string",
                "description": "Value of the enrolment property. Filled for type = date according to RFC 3339"
              },
              "value_time": {
                "type": "string",
                "description": "Value of the enrolment property. Filled for type = time according to RFC 3339"
              },
              "value_datetime": {
                "type": "string",
                "description": "Value of the enrolment property. Filled for type = datetime according to RFC 3339"
              },
              "value_numeric": {
                "type": "number",
                "description": "Value of the enrolment property.  Filled for type = numeric"
              },
              "value_upload_url": {
                "type": "string",
                "description": "Value (URL) of the enrolment property. Filled for type = upload"
              },
              "comment": {
                "type": "string",
                "description": "Comment concerning the value of the enrolment property"
              },
              "piece_of_evidence": {
                "type": "string",
                "description": "Piece of evidence (URL) for the value of the enrolment property"
              }
            }
          }
        }
      },
      "required": [
        "beeple_id",
        "created_at",
        "function"
      ],
      "oneOf": [
        {
          "properties": {
            "wages": {
              "type": "object",
              "properties": {
                "per_hour": {
                  "type": "number",
                  "description": "The wage that is to be paid per hour that is worked in the currency of the company"
                },
                "per_day": {
                  "type": "number",
                  "description": "The wage that is to be paid per day that is worked in the currency of the company"
                },
                "per_team": {
                  "type": "number",
                  "description": "The wage that is to be paid for working in the team in the currency of the company"
                }
              }
            }
          }
        },
        {
          "properties": {
            "wage_scale": {
              "type": "string",
              "description": "If the wages are determined by wage scales, the code of the wage scale that is to be used to determine the wages"
            }
          }
        }
      ]
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "external_id": "C197654",
  "status": "Hello, world!"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "external_id": {
      "type": "string",
      "description": "The identification that was attributed to the created contract"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "accepted",
        "created",
        "denied"
      ],
      "description": "Contract status"
    }
  }
}
Response  202
HideShow
Headers
Content-Type: application/json
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "translations": [
        {
          "language": "EN",
          "error": "Detailed error message"
        }
      ],
      "code": "A001"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "translations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "language": {
                  "type": "string",
                  "description": "The ISO language code"
                },
                "error": {
                  "type": "string",
                  "description": "A detailed error message"
                }
              }
            }
          },
          "code": {
            "type": "string",
            "description": "An optional error code. Beeple will just use this\n\nfor detailed reporting, but will never interpret this value."
          }
        }
      }
    }
  }
}

One Contract

Cancel contract
DELETE/contracts/{contractid}

For each shift of a cancelled confirmed enrolment in Beeple for which a contract request has been sent to the subscribed 3rd party system, Beeple sends a request to cancel the contract in the 3rd party system. Beeple expects a response with

  • if the contract was cancelled: no additional information

  • if the contract was not cancelled: the error code

As in Beeple contracts are not updated but deleted and recreated, Beeple also sends the same request to cancel a contract for each change that possibly impacts a contract, immediately followed by a request to recreate the concerned contract. E.g. if the display color of a project changes in Beeple, this will not result in a request to cancel and to recreate the contract, but if the planned hours change, it will.

There are 2 possible responses. Either the contract is deleted synchronously and the system must respond with a 200 success code, or the contract is deleted asynchrounously and the system must respond with status code 202. In the latter case a contract cancel callback (see next request) needs to be sent later on with an update.

Example URI

DELETE /contracts/87643
URI Parameters
HideShow
contractid
string (required) Example: 87643

The Beeple ID of the contract that needs to be cancelled

Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Body
{
  "company": {
    "name": "My company",
    "beeple_id": "273e949a-bb41-4f36-9526-d1d0a8043c91",
    "enterprise_number": "0101010101",
    "payroll_service_id": "5"
  },
  "beeple_id": 87643,
  "updated_at": "2017-04-01T10:00:00.000+02:00",
  "cancelled_at": "2017-04-01T10:00:00.000+02:00",
  "external_id": "C197654",
  "collaborator": {
    "beeple_id": 2403,
    "external_id": "P77881"
  },
  "will_be_replaced": true,
  "cancellation_reason": {
    "name": {
      "nl": "'wat tekst'",
      "fr": "'du texte'"
    },
    "description": {
      "nl": "'wat tekst'",
      "fr": "'du texte'"
    }
  },
  "cancellation_note": "Other reason"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "company": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the company (tenant). Can change and is mainly for displaying purposes"
        },
        "beeple_id": {
          "type": "string",
          "description": "The ID of the Beeple Tenant (a UUID). Will never change for a given tenant."
        },
        "enterprise_number": {
          "type": "string",
          "description": "Enterprise number of this company"
        },
        "payroll_service_id": {
          "type": "string",
          "description": "A payroll service ID."
        }
      },
      "required": [
        "name",
        "beeple_id"
      ],
      "description": "Company that is sending this information."
    },
    "beeple_id": {
      "type": "number",
      "description": "Identification number within Beeple"
    },
    "updated_at": {
      "type": "string",
      "description": "When the contract was updated"
    },
    "cancelled_at": {
      "type": "string",
      "description": "When the contract was cancelled"
    },
    "external_id": {
      "type": "string",
      "description": "Identification in 3rd party system"
    },
    "collaborator": {
      "type": "object",
      "properties": {
        "beeple_id": {
          "type": "number",
          "description": "Identification number within Beeple"
        },
        "external_id": {
          "type": "string",
          "description": "Identification in 3rd party system"
        }
      },
      "required": [
        "beeple_id",
        "external_id"
      ],
      "description": "Collaborator of the contract"
    },
    "will_be_replaced": {
      "type": "boolean",
      "description": "when true, the contract will be cancelled and then created again"
    },
    "cancellation_reason": {
      "type": "object",
      "properties": {
        "name": {
          "type": "object",
          "properties": {
            "nl": {
              "type": "string"
            },
            "fr": {
              "type": "string"
            }
          }
        },
        "description": {
          "type": "object",
          "properties": {
            "nl": {
              "type": "string"
            },
            "fr": {
              "type": "string"
            }
          }
        }
      },
      "description": "Cancellation reason name and description"
    },
    "cancellation_note": {
      "type": "string",
      "description": "Free text cancellation note"
    }
  },
  "required": [
    "beeple_id",
    "updated_at",
    "cancelled_at",
    "external_id"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Response  202
HideShow
Headers
Content-Type: application/json

Contract Callback

Updates & Cancellation
PATCH/api/v1/incoming/contracts/callback

If the 3rd party system needs time to treat the request to create or cancel a contract, it can send the result of the treatment asynchronously using this request. This callback can also be used to update the Beeple system if the status changed in the 3rd party system.

This request is sent from the 3rd party system to Beeple, unlike most other requests in this API

Example URI

PATCH /api/v1/incoming/contracts/callback
Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Body
{
  "contract": {
    "company": {
      "name": "My company",
      "beeple_id": "273e949a-bb41-4f36-9526-d1d0a8043c91",
      "enterprise_number": "0101010101",
      "payroll_service_id": "5"
    },
    "beeple_id": 87643,
    "external_id": "C197654",
    "collaborator": {
      "beeple_id": 2403,
      "external_id": "P77881"
    },
    "status": "approved"
  },
  "errors": [
    {
      "translations": [
        {
          "language": "EN",
          "error": "Detailed error message"
        }
      ],
      "code": "A001"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "contract": {
      "type": "object",
      "properties": {
        "company": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Name of the company (tenant). Can change and is mainly for displaying purposes"
            },
            "beeple_id": {
              "type": "string",
              "description": "The ID of the Beeple Tenant (a UUID). Will never change for a given tenant."
            },
            "enterprise_number": {
              "type": "string",
              "description": "Enterprise number of this company"
            },
            "payroll_service_id": {
              "type": "string",
              "description": "A payroll service ID."
            }
          },
          "required": [
            "name",
            "beeple_id"
          ],
          "description": "Company that is sending this information."
        },
        "beeple_id": {
          "type": "number",
          "description": "Identification number within Beeple"
        },
        "external_id": {
          "type": "string",
          "description": "Identification in 3rd party system"
        },
        "collaborator": {
          "type": "object",
          "properties": {
            "beeple_id": {
              "type": "number",
              "description": "Identification number within Beeple"
            },
            "external_id": {
              "type": "string",
              "description": "Identification in 3rd party system"
            }
          },
          "required": [
            "beeple_id",
            "external_id"
          ],
          "description": "Collaborator of the contract"
        },
        "status": {
          "type": "string",
          "enum": [
            "approved",
            "created",
            "denied"
          ]
        }
      },
      "required": [
        "beeple_id",
        "external_id",
        "status"
      ]
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "translations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "language": {
                  "type": "string",
                  "description": "The ISO language code"
                },
                "error": {
                  "type": "string",
                  "description": "A detailed error message"
                }
              }
            }
          },
          "code": {
            "type": "string",
            "description": "An optional error code. Beeple will just use this\n\nfor detailed reporting, but will never interpret this value."
          }
        }
      }
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json

Costs

Costs

Report costs
POST/costs

For each approval of costs in Beeple, Beeple transfers this information to the subscribed 3rd party system. The approved costs cannot be changed afterwards.

Report costs

Example URI

POST /costs
Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Body
{
  "company": {
    "name": "My company",
    "beeple_id": "273e949a-bb41-4f36-9526-d1d0a8043c91",
    "enterprise_number": "0101010101",
    "payroll_service_id": "5"
  },
  "contract": {
    "company": {
      "name": "My company",
      "beeple_id": "273e949a-bb41-4f36-9526-d1d0a8043c91",
      "enterprise_number": "0101010101",
      "payroll_service_id": "5"
    },
    "beeple_id": 87643,
    "external_id": "C197654",
    "collaborator": {
      "beeple_id": 2403,
      "external_id": "P77881"
    }
  },
  "costs": {
    "name": "Lunch",
    "description": "Lunch with Ms. Bartlett to discuss contract",
    "type": "Cost",
    "code": "553",
    "date": "2017-04-01",
    "start_at": "2017-04-01T10:10:00.000+02:00",
    "end_at": "2017-04-01T10:10:00.000+02:00",
    "base": "hour",
    "formula_unit": "currency",
    "amount_per_base": 2.5,
    "number_of_bases": 5,
    "amount": 12.5,
    "valorization": true,
    "refuse_payout": false
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "company": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the company (tenant). Can change and is mainly for displaying purposes"
        },
        "beeple_id": {
          "type": "string",
          "description": "The ID of the Beeple Tenant (a UUID). Will never change for a given tenant."
        },
        "enterprise_number": {
          "type": "string",
          "description": "Enterprise number of this company"
        },
        "payroll_service_id": {
          "type": "string",
          "description": "A payroll service ID."
        }
      },
      "required": [
        "name",
        "beeple_id"
      ],
      "description": "Company that is sending this information."
    },
    "contract": {
      "type": "object",
      "properties": {
        "company": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Name of the company (tenant). Can change and is mainly for displaying purposes"
            },
            "beeple_id": {
              "type": "string",
              "description": "The ID of the Beeple Tenant (a UUID). Will never change for a given tenant."
            },
            "enterprise_number": {
              "type": "string",
              "description": "Enterprise number of this company"
            },
            "payroll_service_id": {
              "type": "string",
              "description": "A payroll service ID."
            }
          },
          "required": [
            "name",
            "beeple_id"
          ],
          "description": "Company that is sending this information."
        },
        "beeple_id": {
          "type": "number",
          "description": "Identification number within Beeple"
        },
        "external_id": {
          "type": "string",
          "description": "Identification in 3rd party system"
        },
        "collaborator": {
          "type": "object",
          "properties": {
            "beeple_id": {
              "type": "number",
              "description": "Identification number within Beeple"
            },
            "external_id": {
              "type": "string",
              "description": "Identification in 3rd party system"
            }
          },
          "required": [
            "beeple_id",
            "external_id"
          ],
          "description": "Collaborator of the contract"
        }
      },
      "required": [
        "beeple_id",
        "external_id"
      ],
      "description": "Contract for which costs are reported"
    },
    "costs": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "Cost",
            "Premium"
          ],
          "description": "Type of costs"
        },
        "code": {
          "type": "string",
          "description": "Code of the cost"
        },
        "date": {
          "type": "string",
          "description": "When the cost was incurred according RFC 3339."
        },
        "start_at": {
          "type": "string",
          "description": "When the shift associated to this cost starts according RFC 3339."
        },
        "end_at": {
          "type": "string",
          "description": "When the shift associated to this cost ends according RFC 3339."
        },
        "base": {
          "type": "string",
          "enum": [
            "hour",
            "day",
            "km",
            "piece"
          ],
          "description": "Base on which the amount is calculated"
        },
        "formula_unit": {
          "type": "string",
          "enum": [
            "currency",
            "percentage"
          ],
          "description": "Formula unit with which the amount is calculated"
        },
        "amount_per_base": {
          "type": "number",
          "description": "Amount in the currency of the company to be paid or percentage to be applied for 1 base. This is only filled, if valorisation is done in Beeple"
        },
        "number_of_bases": {
          "type": "number",
          "description": "Number of times the base is paid. . This is only filled, if valorisation is done in Beeple"
        },
        "amount": {
          "type": "number",
          "description": "Amount to be paid in the currency of the company. . This is only filled, if valorisation is done in Beeple"
        },
        "valorization": {
          "type": "boolean",
          "description": "true or false as defined for the payroll integration for this type of cost"
        },
        "refuse_payout": {
          "type": "boolean",
          "description": "true when the admin selected \"Do not pay\" when processing the cost"
        }
      },
      "required": [
        "name",
        "type",
        "date",
        "base",
        "formula_unit"
      ]
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json

Unplanned Costs

Report unplanned costs
POST/unplanned_costs

For each approval of costs without planning in Beeple, Beeple transfers this information to the subscribed 3rd party system. The approved unplanned costs cannot be changed afterwards.

Report unplanned costs

Example URI

POST /unplanned_costs
Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Body
{
  "company": {
    "name": "My company",
    "beeple_id": "273e949a-bb41-4f36-9526-d1d0a8043c91",
    "enterprise_number": "0101010101",
    "payroll_service_id": "5"
  },
  "collaborator": {
    "beeple_id": 2403,
    "external_id": "P77881"
  },
  "unplanned_costs": {
    "name": "Lunch",
    "description": "Lunch with Ms. Bartlett to discuss contract",
    "type": "Cost",
    "code": "553",
    "date": "2017-04-01",
    "base": "hour",
    "formula_unit": "currency",
    "amount_per_base": 2.5,
    "number_of_bases": 5,
    "amount": 12.5,
    "valorization": true,
    "refuse_payout": false
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "company": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the company (tenant). Can change and is mainly for displaying purposes"
        },
        "beeple_id": {
          "type": "string",
          "description": "The ID of the Beeple Tenant (a UUID). Will never change for a given tenant."
        },
        "enterprise_number": {
          "type": "string",
          "description": "Enterprise number of this company"
        },
        "payroll_service_id": {
          "type": "string",
          "description": "A payroll service ID."
        }
      },
      "required": [
        "name",
        "beeple_id"
      ],
      "description": "Company that is sending this information."
    },
    "collaborator": {
      "type": "object",
      "properties": {
        "beeple_id": {
          "type": "number",
          "description": "Identification number within Beeple"
        },
        "external_id": {
          "type": "string",
          "description": "Identification in 3rd party system"
        }
      },
      "required": [
        "beeple_id",
        "external_id"
      ],
      "description": "Collaborator for which worked hours are reported"
    },
    "unplanned_costs": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "Cost",
            "Premium"
          ],
          "description": "Type of costs"
        },
        "code": {
          "type": "string",
          "description": "Code of the cost"
        },
        "date": {
          "type": "string",
          "description": "When the cost was incurred according RFC 3339."
        },
        "base": {
          "type": "string",
          "enum": [
            "hour",
            "day",
            "km",
            "piece"
          ],
          "description": "Base on which the amount is calculated"
        },
        "formula_unit": {
          "type": "string",
          "enum": [
            "currency",
            "percentage"
          ],
          "description": "Formula unit with which the amount is calculated"
        },
        "amount_per_base": {
          "type": "number",
          "description": "Amount in the currency of the company to be paid or percentage to be applied for 1 base. This is only filled, if valorisation is done in Beeple"
        },
        "number_of_bases": {
          "type": "number",
          "description": "Number of times the base is paid. . This is only filled, if valorisation is done in Beeple"
        },
        "amount": {
          "type": "number",
          "description": "Amount to be paid in the currency of the company. . This is only filled, if valorisation is done in Beeple"
        },
        "valorization": {
          "type": "boolean",
          "description": "true or false as defined for the payroll integration for this type of cost"
        },
        "refuse_payout": {
          "type": "boolean",
          "description": "true when the admin selected \"Do not pay\" when processing the cost"
        }
      },
      "required": [
        "name",
        "type",
        "date",
        "base",
        "formula_unit"
      ]
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json

Hour registration

Worked hours

Report worked hours
POST/worked_hours

For each approval of reported hours in Beeple, Beeple transfers this information to the subscribed 3rd party system. The approved hours cannot be changed afterwards. These will only be executed when the project is in a created state.

Report worked hours

Example URI

POST /worked_hours
Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Body
{
  "company": {
    "name": "My company",
    "beeple_id": "273e949a-bb41-4f36-9526-d1d0a8043c91",
    "enterprise_number": "0101010101",
    "payroll_service_id": "5"
  },
  "contract": {
    "company": {
      "name": "My company",
      "beeple_id": "273e949a-bb41-4f36-9526-d1d0a8043c91",
      "enterprise_number": "0101010101",
      "payroll_service_id": "5"
    },
    "beeple_id": 87643,
    "external_id": "C197654",
    "collaborator": {
      "beeple_id": 2403,
      "external_id": "P77881"
    }
  },
  "worked_hours": {
    "code": "other",
    "start": "2017-04-01T10:10:00.000+02:00",
    "end": "2017-04-01T19:05:00.000+02:00",
    "duration": "08:55",
    "break_duration": "00:30",
    "work_duration": "08:25",
    "remark": "Reviewed by Adam and approved by Betsy",
    "absent": false,
    "absence_reason": "Illness",
    "confirmed_at": "2017-04-01T10:10:00.000+02:00"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "company": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the company (tenant). Can change and is mainly for displaying purposes"
        },
        "beeple_id": {
          "type": "string",
          "description": "The ID of the Beeple Tenant (a UUID). Will never change for a given tenant."
        },
        "enterprise_number": {
          "type": "string",
          "description": "Enterprise number of this company"
        },
        "payroll_service_id": {
          "type": "string",
          "description": "A payroll service ID."
        }
      },
      "required": [
        "name",
        "beeple_id"
      ],
      "description": "Company that is sending this information."
    },
    "contract": {
      "type": "object",
      "properties": {
        "company": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Name of the company (tenant). Can change and is mainly for displaying purposes"
            },
            "beeple_id": {
              "type": "string",
              "description": "The ID of the Beeple Tenant (a UUID). Will never change for a given tenant."
            },
            "enterprise_number": {
              "type": "string",
              "description": "Enterprise number of this company"
            },
            "payroll_service_id": {
              "type": "string",
              "description": "A payroll service ID."
            }
          },
          "required": [
            "name",
            "beeple_id"
          ],
          "description": "Company that is sending this information."
        },
        "beeple_id": {
          "type": "number",
          "description": "Identification number within Beeple"
        },
        "external_id": {
          "type": "string",
          "description": "Identification in 3rd party system"
        },
        "collaborator": {
          "type": "object",
          "properties": {
            "beeple_id": {
              "type": "number",
              "description": "Identification number within Beeple"
            },
            "external_id": {
              "type": "string",
              "description": "Identification in 3rd party system"
            }
          },
          "required": [
            "beeple_id",
            "external_id"
          ],
          "description": "Collaborator of the contract"
        }
      },
      "required": [
        "beeple_id",
        "external_id"
      ],
      "description": "Contract for which worked hours are reported"
    }
  },
  "oneOf": [
    {
      "properties": {
        "worked_hours": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string",
              "enum": [
                "other",
                "collaborator",
                "planned"
              ],
              "description": "Which hours are approved."
            },
            "start": {
              "type": "string",
              "description": "When the collaborator started working for the reported shift according RFC 3339."
            },
            "end": {
              "type": "string",
              "description": "When the collaborator stopped working for the reported shift according RFC 3339."
            },
            "duration": {
              "type": "string",
              "description": "How long the collaborator was present in the reported shift according RFC 3339."
            },
            "break_duration": {
              "type": "string",
              "description": "How long the collaborator didn't to work in the reported shift according RFC 3339. Can be 00:00."
            },
            "work_duration": {
              "type": "string",
              "description": "How long the collaborator worked in the reported shift according RFC 3339. Can be 00:00."
            },
            "remark": {
              "type": "string",
              "description": "Any remarks saved with the worked hour"
            },
            "absent": {
              "type": "boolean",
              "description": "true if the collaborator was absent, false otherwise"
            },
            "absence_reason": {
              "type": "string",
              "description": "The reason of the absence as a string. Can be empty string."
            },
            "confirmed_at": {
              "type": "string",
              "description": "When the worked hour was confirmed according RFC 3339."
            }
          },
          "required": [
            "start",
            "end",
            "duration",
            "break_duration"
          ],
          "description": "Sent regardless of the collaborator being absent"
        }
      }
    },
    {
      "properties": {
        "absence_reason": {
          "type": "object",
          "properties": {
            "description": {
              "type": "string",
              "description": "The absence reason description"
            },
            "code": {
              "type": "string",
              "description": "The code assigned for the absence reason for this payroll integration"
            }
          },
          "description": "Only sent if collaborator was absent"
        }
      }
    }
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json

Unplanned hours/absence

Note that if your organisation has enabled the latest Availabilities 2.0 module, the /unplanned_hours endpoint will not receive notifications; all unplanned hours/absences will be reported to the /availabilities endpoint

Report unplanned hours/absences
POST/unplanned_hours

For each approval of unplanned hours (and absences) in Beeple, Beeple transfers this information to the subscribed 3rd party system. The unplanned hours cannot be changed afterwards.

Report unplanned hours

Example URI

POST /unplanned_hours
Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Body
{
  "company": {
    "name": "My company",
    "beeple_id": "273e949a-bb41-4f36-9526-d1d0a8043c91",
    "enterprise_number": "0101010101",
    "payroll_service_id": "5"
  },
  "collaborator": {
    "beeple_id": 2403,
    "external_id": "P77881"
  },
  "unplanned_hours": {
    "code": "ABC1",
    "start": "2017-04-01T10:10:00.000+02:00",
    "end": "2017-04-01T19:05:00.000+02:00",
    "duration": "08:55",
    "remark": "Reviewed by Adam and approved by Betsy",
    "absent": false,
    "absence_reason": "Illness",
    "confirmed_at": "2017-04-01T10:10:00.000+02:00"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "company": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the company (tenant). Can change and is mainly for displaying purposes"
        },
        "beeple_id": {
          "type": "string",
          "description": "The ID of the Beeple Tenant (a UUID). Will never change for a given tenant."
        },
        "enterprise_number": {
          "type": "string",
          "description": "Enterprise number of this company"
        },
        "payroll_service_id": {
          "type": "string",
          "description": "A payroll service ID."
        }
      },
      "required": [
        "name",
        "beeple_id"
      ],
      "description": "Company that is sending this information."
    },
    "collaborator": {
      "type": "object",
      "properties": {
        "beeple_id": {
          "type": "number",
          "description": "Identification number within Beeple"
        },
        "external_id": {
          "type": "string",
          "description": "Identification in 3rd party system"
        }
      },
      "required": [
        "beeple_id",
        "external_id"
      ],
      "description": "Collaborator for which unplanned hours are reported"
    }
  },
  "oneOf": [
    {
      "properties": {
        "unplanned_hours": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string",
              "description": "The code assigned for the unplanned hour/absence for this payroll integration"
            },
            "start": {
              "type": "string",
              "description": "When the unplanned hours period starts according RFC 3339."
            },
            "end": {
              "type": "string",
              "description": "When the unplanned hours period ends according RFC 3339."
            },
            "duration": {
              "type": "string",
              "description": "Duration of the unplanned hours/absence according RFC 3339."
            },
            "remark": {
              "type": "string",
              "description": "Any remarks saved with the unplanned hour"
            },
            "absent": {
              "type": "boolean",
              "description": "true if the record is an unplanned absence, false otherwise"
            },
            "absence_reason": {
              "type": "string",
              "description": "The reason of the absence as a string. Can be empty string."
            },
            "confirmed_at": {
              "type": "string",
              "description": "When the unplanned hour/absence was confirmed according RFC 3339."
            }
          },
          "required": [
            "start",
            "end",
            "duration"
          ],
          "description": "Sent regardless of the collaborator being absent (unplanned absence)"
        }
      }
    },
    {
      "properties": {
        "absence_reason": {
          "type": "object",
          "properties": {
            "description": {
              "type": "string",
              "description": "The absence reason description"
            },
            "code": {
              "type": "string",
              "description": "The code assigned for the absence reason for this payroll integration"
            }
          },
          "description": "Only sent if the record is for an absence"
        }
      }
    }
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json

Availabilities

List of Availabilities

Create (un)availabilities
POST/availabilities

An Availability in Beeple can represent an absence (absent: true) or an available time explicitly reported (absent: false).

For (un)availability created in Beeple, Beeple transfers this information to the subscribed 3rd party system.

Example URI

POST /availabilities
Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Body
{
  "company": {
    "name": "My company",
    "beeple_id": "273e949a-bb41-4f36-9526-d1d0a8043c91",
    "enterprise_number": "0101010101",
    "payroll_service_id": "5"
  },
  "collaborator": {
    "beeple_id": 2403,
    "external_id": "P77881"
  },
  "availabilities": {
    "id": "2",
    "code": "ABC1",
    "day_part_id": "13",
    "id_availability_type": "4",
    "name": "Illness",
    "description": "Sickness with medical certification",
    "available": true,
    "start": "2017-04-01T10:10:00.000+02:00",
    "end": "2017-04-01T19:05:00.000+02:00",
    "duration": "08:55",
    "remark": "Reviewed by Adam and approved by Betsy",
    "requested_at": "2017-04-01T19:05:00.000+02:00",
    "requested_by `1105`": "Hello, world!",
    "confirmed_at": "2017-04-01T10:10:00.000+02:00",
    "status": "pending",
    "beeple_approval_status": "not_required",
    "payroll_approval_status": "not_required",
    "pieces_of_evidence": [
      {
        "id": "546",
        "filename": "Maternity_leave.pdf",
        "url": "https://my.beeple.eu/evidences/87234"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "company": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the company (tenant). Can change and is mainly for displaying purposes"
        },
        "beeple_id": {
          "type": "string",
          "description": "The ID of the Beeple Tenant (a UUID). Will never change for a given tenant."
        },
        "enterprise_number": {
          "type": "string",
          "description": "Enterprise number of this company"
        },
        "payroll_service_id": {
          "type": "string",
          "description": "A payroll service ID."
        }
      },
      "required": [
        "name",
        "beeple_id"
      ],
      "description": "Company that is sending this information."
    },
    "collaborator": {
      "type": "object",
      "properties": {
        "beeple_id": {
          "type": "number",
          "description": "Identification number within Beeple"
        },
        "external_id": {
          "type": "string",
          "description": "Identification in 3rd party system"
        }
      },
      "required": [
        "beeple_id",
        "external_id"
      ],
      "description": "Collaborator for which (un)availabilities are reported"
    }
  },
  "oneOf": [
    {
      "properties": {
        "availabilities": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "The id of the availability (note this same id will come at the end of the url for any subsequent update (PATCH) and remove (DELETE) requests)"
            },
            "code": {
              "type": "string",
              "description": "The code assigned for the (un)availability for this payroll integration"
            },
            "day_part_id": {
              "type": "string",
              "description": "The id od a Day Part that this availability is tied to (can be empty if no day part is set)"
            },
            "id_availability_type": {
              "type": "string",
              "description": "The id of the Type of Availability associated with this availability."
            },
            "name": {
              "type": "string",
              "description": "The name of the (un)availability as a string. Can be empty string."
            },
            "description": {
              "type": "string",
              "description": "The reason of the (un)availability as a string. Can be empty string."
            },
            "available": {
              "type": "boolean",
              "description": "true if the record is an availability, false if it is an unavailability"
            },
            "start": {
              "type": "string",
              "description": "Period starts according RFC 3339."
            },
            "end": {
              "type": "string",
              "description": "Period ends according RFC 3339."
            },
            "duration": {
              "type": "string",
              "description": "Duration of the (un)availability according RFC 3339. Can be empty."
            },
            "remark": {
              "type": "string",
              "description": "Any remarks saved with the (un)availability"
            },
            "requested_at": {
              "type": "string",
              "description": "Date and time the availability request was made RFC 3339."
            },
            "requested_by `1105`": {
              "type": "string",
              "description": "The id of the collaborator or admin that requested this (un)availability"
            },
            "confirmed_at": {
              "type": "string",
              "description": "When the (un)availability was confirmed (approved or rejected) according RFC 3339."
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "normal",
                "rejected"
              ],
              "description": "The status of the availability"
            },
            "beeple_approval_status": {
              "type": "string",
              "enum": [
                "not_required",
                "unknown",
                "accepted",
                "rejected"
              ],
              "description": "The status of the availability for the beeple planner"
            },
            "payroll_approval_status": {
              "type": "string",
              "enum": [
                "not_required",
                "unknown",
                "accepted",
                "rejected"
              ],
              "description": "The status of the availability for the payroll service"
            },
            "pieces_of_evidence": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "The ID of the evidence file"
                  },
                  "filename": {
                    "type": "string",
                    "description": "The name of the file"
                  },
                  "url": {
                    "type": "string",
                    "description": "an url where an API client my download a copy of the file. Note that this URL is only temporary valid"
                  }
                }
              },
              "description": "An array of files attached to the availability as pieces of evidence"
            }
          },
          "required": [
            "start",
            "end",
            "requested_at",
            "status",
            "beeple_approval_status",
            "payroll_approval_status"
          ]
        }
      }
    }
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json

Update (un)availability
PATCH/availabilities/{id}

Once created, each change in an (un)availability will produce a PATCH request to the subscribed 3rd party system, with updated information about the availability. If there is a value for confirmed_at, the availability has been approved (is status is normal) or rejected (id status is rejected) the (un)availability cannot be changed after being approved or rejected.

Example URI

PATCH /availabilities/1454
URI Parameters
HideShow
id
string (required) Example: 1454

The Beeple ID of the availability

Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Body
{
  "company": {
    "name": "My company",
    "beeple_id": "273e949a-bb41-4f36-9526-d1d0a8043c91",
    "enterprise_number": "0101010101",
    "payroll_service_id": "5"
  },
  "collaborator": {
    "beeple_id": 2403,
    "external_id": "P77881"
  },
  "availabilities": {
    "id": "2",
    "code": "ABC1",
    "day_part_id": "13",
    "id_availability_type": "4",
    "name": "Illness",
    "description": "Sickness with medical certification",
    "available": true,
    "start": "2017-04-01T10:10:00.000+02:00",
    "end": "2017-04-01T19:05:00.000+02:00",
    "duration": "08:55",
    "remark": "Reviewed by Adam and approved by Betsy",
    "requested_at": "2017-04-01T19:05:00.000+02:00",
    "requested_by `1105`": "Hello, world!",
    "confirmed_at": "2017-04-01T10:10:00.000+02:00",
    "status": "pending",
    "beeple_approval_status": "not_required",
    "payroll_approval_status": "not_required",
    "pieces_of_evidence": [
      {
        "id": "546",
        "filename": "Maternity_leave.pdf",
        "url": "https://my.beeple.eu/evidences/87234"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "company": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the company (tenant). Can change and is mainly for displaying purposes"
        },
        "beeple_id": {
          "type": "string",
          "description": "The ID of the Beeple Tenant (a UUID). Will never change for a given tenant."
        },
        "enterprise_number": {
          "type": "string",
          "description": "Enterprise number of this company"
        },
        "payroll_service_id": {
          "type": "string",
          "description": "A payroll service ID."
        }
      },
      "required": [
        "name",
        "beeple_id"
      ],
      "description": "Company that is sending this information."
    },
    "collaborator": {
      "type": "object",
      "properties": {
        "beeple_id": {
          "type": "number",
          "description": "Identification number within Beeple"
        },
        "external_id": {
          "type": "string",
          "description": "Identification in 3rd party system"
        }
      },
      "required": [
        "beeple_id",
        "external_id"
      ],
      "description": "Collaborator for which (un)availabilities are reported"
    }
  },
  "oneOf": [
    {
      "properties": {
        "availabilities": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "The id of the availability (note this same id will come at the end of the url for any subsequent update (PATCH) and remove (DELETE) requests)"
            },
            "code": {
              "type": "string",
              "description": "The code assigned for the (un)availability for this payroll integration"
            },
            "day_part_id": {
              "type": "string",
              "description": "The id od a Day Part that this availability is tied to (can be empty if no day part is set)"
            },
            "id_availability_type": {
              "type": "string",
              "description": "The id of the Type of Availability associated with this availability."
            },
            "name": {
              "type": "string",
              "description": "The name of the (un)availability as a string. Can be empty string."
            },
            "description": {
              "type": "string",
              "description": "The reason of the (un)availability as a string. Can be empty string."
            },
            "available": {
              "type": "boolean",
              "description": "true if the record is an availability, false if it is an unavailability"
            },
            "start": {
              "type": "string",
              "description": "Period starts according RFC 3339."
            },
            "end": {
              "type": "string",
              "description": "Period ends according RFC 3339."
            },
            "duration": {
              "type": "string",
              "description": "Duration of the (un)availability according RFC 3339. Can be empty."
            },
            "remark": {
              "type": "string",
              "description": "Any remarks saved with the (un)availability"
            },
            "requested_at": {
              "type": "string",
              "description": "Date and time the availability request was made RFC 3339."
            },
            "requested_by `1105`": {
              "type": "string",
              "description": "The id of the collaborator or admin that requested this (un)availability"
            },
            "confirmed_at": {
              "type": "string",
              "description": "When the (un)availability was confirmed (approved or rejected) according RFC 3339."
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "normal",
                "rejected"
              ],
              "description": "The status of the availability"
            },
            "beeple_approval_status": {
              "type": "string",
              "enum": [
                "not_required",
                "unknown",
                "accepted",
                "rejected"
              ],
              "description": "The status of the availability for the beeple planner"
            },
            "payroll_approval_status": {
              "type": "string",
              "enum": [
                "not_required",
                "unknown",
                "accepted",
                "rejected"
              ],
              "description": "The status of the availability for the payroll service"
            },
            "pieces_of_evidence": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "The ID of the evidence file"
                  },
                  "filename": {
                    "type": "string",
                    "description": "The name of the file"
                  },
                  "url": {
                    "type": "string",
                    "description": "an url where an API client my download a copy of the file. Note that this URL is only temporary valid"
                  }
                }
              },
              "description": "An array of files attached to the availability as pieces of evidence"
            }
          },
          "required": [
            "start",
            "end",
            "requested_at",
            "status",
            "beeple_approval_status",
            "payroll_approval_status"
          ]
        }
      }
    }
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json

Remove (un)availability
DELETE/availabilities/{id}

Sent if the availability is deleted in Beeple before it has been approved or rejected.

Example URI

DELETE /availabilities/1454
URI Parameters
HideShow
id
string (required) Example: 1454

The Beeple ID of the availability

Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Response  200
HideShow
Headers
Content-Type: application/json

One Time login

One Time login

This request is sent by the Beeple system and is used to allow the user to login to a website dashboard of the payroll integrator.

Request a one time login
POST/one-time-login

Example URI

POST /one-time-login
Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Body
{
  "company": {
    "name": "My company",
    "beeple_id": "273e949a-bb41-4f36-9526-d1d0a8043c91",
    "enterprise_number": "0101010101",
    "payroll_service_id": "5"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "company": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the company (tenant). Can change and is mainly for displaying purposes"
        },
        "beeple_id": {
          "type": "string",
          "description": "The ID of the Beeple Tenant (a UUID). Will never change for a given tenant."
        },
        "enterprise_number": {
          "type": "string",
          "description": "Enterprise number of this company"
        },
        "payroll_service_id": {
          "type": "string",
          "description": "A payroll service ID."
        }
      },
      "required": [
        "name",
        "beeple_id"
      ],
      "description": "Company that is sending this information."
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "one_time_url": "http://example.org/dashboard?nonce=1234"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "one_time_url": {
      "type": "string",
      "description": "The URL the user should be sent to. The link should be only valid\n\nonce and be valid for only a linited amount of time (eg. 5 minutes)."
    }
  }
}

Notifications

Notifications

A payroll integration may call this endpoint to handle notifications that will show up in the admin dashboard within the Beeple Web applicatioon.

Create an external notification
POST/api/v1/incoming/notifications

Example URI

POST /api/v1/incoming/notifications
Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Body
{
  "company": {
    "name": "My company",
    "beeple_id": "273e949a-bb41-4f36-9526-d1d0a8043c91",
    "enterprise_number": "0101010101",
    "payroll_service_id": "5"
  },
  "notification": {
    "collaborator_id": 1106,
    "custom_data": {
      "message": [
        {
          "language": "en",
          "message": "Your account is linked"
        }
      ]
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "company": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the company (tenant). Can change and is mainly for displaying purposes"
        },
        "beeple_id": {
          "type": "string",
          "description": "The ID of the Beeple Tenant (a UUID). Will never change for a given tenant."
        },
        "enterprise_number": {
          "type": "string",
          "description": "Enterprise number of this company"
        },
        "payroll_service_id": {
          "type": "string",
          "description": "A payroll service ID."
        }
      },
      "required": [
        "name",
        "beeple_id"
      ],
      "description": "Company that is sending this information."
    },
    "notification": {
      "type": "object",
      "properties": {
        "collaborator_id": {
          "type": "number",
          "description": "Identification number within Beeple"
        },
        "custom_data": {
          "type": "object",
          "properties": {
            "message": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "language": {
                    "type": "string",
                    "description": "[ISO 639-1 code](https://en.wikipedia.org/wiki/ISO_639-1) of the language used in `message`. To check the currently supported languages in Beeple web application go to Settings > General."
                  },
                  "message": {
                    "type": "string",
                    "description": "the content of your message expressed in the specific `language`"
                  }
                },
                "required": [
                  "language",
                  "message"
                ]
              },
              "description": "The notification message sent as a collection of the message translations in different languages."
            }
          }
        }
      },
      "required": [
        "collaborator_id"
      ],
      "description": "The details of the notification to be created."
    }
  }
}
Response  201
HideShow
Headers
Content-Type: application/json

Externally created Availabilities

Availabilities

A payroll integration may call this endpoint to create or remove collaborators availabilities in the Beeple Web applicatioon.

Create availability
POST/api/v1/incoming/availabilities

Example URI

POST /api/v1/incoming/availabilities
Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Body
{
  "company": {
    "name": "My company",
    "beeple_id": "273e949a-bb41-4f36-9526-d1d0a8043c91",
    "enterprise_number": "0101010101",
    "payroll_service_id": "5"
  },
  "availability": {
    "collaborator_id": 1106,
    "id": 1,
    "availability_type_id": 1,
    "starts_at": "2017-04-01",
    "ends_at": "2017-04-01",
    "whole_day": true,
    "start_time": "06:00",
    "end_time": "23:59",
    "period": "single_date",
    "payroll_code_id": 1,
    "duration_in_hours": 8,
    "day_part_id": 1,
    "remark_by_collaborator": "Cannot be present on the 20th at 8am",
    "is_approved": true,
    "approved_by_id": 5,
    "admin_reject_reason": "Did not attach evidence",
    "payroll_approval_status": "not_required",
    "payroll_reject_reason": "An example",
    "payroll_approved": true,
    "payroll_approved_by": "Some name",
    "payroll_approved_at": "2019-04-01T06:00:00.000+00:00",
    "is_locked": true,
    "locked_by_id": 5,
    "repetition_schedule_attributes": {
      "repeat_until: `a_date`": "a_date",
      "repeats_every": 1,
      "end_date: `2017-04-01` (string, required) - A final date when the repetition ends according RFC 3339. (only if `repeat_until` is `a_date`)": "Hello, world!",
      "occurrences": 3,
      "monthly_repeat_system": "day_of_month",
      "weekly_repeats_on": [
        1
      ]
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "company": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the company (tenant). Can change and is mainly for displaying purposes"
        },
        "beeple_id": {
          "type": "string",
          "description": "The ID of the Beeple Tenant (a UUID). Will never change for a given tenant."
        },
        "enterprise_number": {
          "type": "string",
          "description": "Enterprise number of this company"
        },
        "payroll_service_id": {
          "type": "string",
          "description": "A payroll service ID."
        }
      },
      "required": [
        "name",
        "beeple_id"
      ],
      "description": "Company that is sending this information."
    },
    "availability": {
      "type": "object",
      "properties": {
        "collaborator_id": {
          "type": "number",
          "description": "Identification number of the collaborator within Beeple"
        },
        "id": {
          "type": "number",
          "description": "The ID of the collaborator availability"
        },
        "availability_type_id": {
          "type": "number",
          "description": "The id of the Availability Type associated with this collaborator availability"
        },
        "starts_at": {
          "type": "string",
          "description": "Period starts according RFC 3339."
        },
        "ends_at": {
          "type": "string",
          "description": "Period ends according RFC 3339."
        },
        "whole_day": {
          "type": "boolean",
          "description": "when true, the availability will run from starts at 00:00 to ends at 00:00 (midnight to midnight)"
        },
        "start_time": {
          "type": "string",
          "description": "Time of availability start in HH:MM 24 hour format"
        },
        "end_time": {
          "type": "string",
          "description": "Time of availability end in HH:MM 24 hour format"
        },
        "period": {
          "type": "string",
          "enum": [
            "single_date",
            "repeat_daily",
            "repeat_weekly",
            "repeat_monthly"
          ],
          "description": "a single date, a daily, weekly or monthly recurring availability."
        },
        "payroll_code_id": {
          "type": "number",
          "description": "The id of an Availability Type Payroll Code"
        },
        "duration_in_hours": {
          "type": "number",
          "description": "The number of hours associated with this availability"
        },
        "day_part_id": {
          "type": "number",
          "description": "The id of a Day Part"
        },
        "remark_by_collaborator": {
          "type": "string",
          "description": "The remark provided with the availability"
        },
        "is_approved": {
          "type": "boolean",
          "description": "set to true when the availability is approved. False when rejected."
        },
        "approved_by_id": {
          "type": "number",
          "description": "The ID of the admin that approved the availability"
        },
        "admin_reject_reason": {
          "type": "string",
          "description": "an optional remark that describes the reason for rejection"
        },
        "payroll_approval_status": {
          "type": "string",
          "enum": [
            "not_required",
            "unknown",
            "accepted",
            "rejected"
          ],
          "description": "The status according to the payroll. Should ideally only be set to accepted or rejected by the API"
        },
        "payroll_reject_reason": {
          "type": "string",
          "description": "Reason why the payroll rejected the request. Only applicable if payroll_approval_status is rejected"
        },
        "payroll_approved": {
          "type": "boolean",
          "description": "true if payroll service approves the availability; false if payroll service rejects the availability"
        },
        "payroll_approved_by": {
          "type": "string",
          "description": "A name or identification received from the payroll indicating who approved or rejected the availability"
        },
        "payroll_approved_at": {
          "type": "string",
          "description": "Timestamp according RFC 3339 of when availability was approved or rejected."
        },
        "is_locked": {
          "type": "boolean",
          "description": "whether the availability is locked or not (only useful when setting Enable availability locking is set to Yes)"
        },
        "locked_by_id": {
          "type": "number",
          "description": "The ID of the admin or collaborator that locked the availability"
        },
        "repetition_schedule_attributes": {
          "type": "object",
          "properties": {
            "repeat_until: `a_date`": {
              "type": "string",
              "enum": [
                "a_date",
                "number_of_repetitions"
              ],
              "description": "How to determine the end date of the repetition"
            },
            "repeats_every": {
              "type": "number",
              "description": "the interval at which the repetition occurs: every N days, weeks or months"
            },
            "end_date: `2017-04-01` (string, required) - A final date when the repetition ends according RFC 3339. (only if `repeat_until` is `a_date`)": {
              "type": "string"
            },
            "occurrences": {
              "type": "number"
            },
            "monthly_repeat_system": {
              "type": "string",
              "enum": [
                "day_of_month",
                "week_of_month"
              ],
              "description": "When does the repetition occur: `day_of_month` (Monthly, on the 25)  `week_of_month` (Monthly, on the fourth Thursday)"
            },
            "weekly_repeats_on": {
              "type": "array"
            }
          },
          "required": [
            "repeats_every"
          ],
          "description": "The definition of how the availability will repeat (only if `period` is `repeat_weekly` or `repeat_monthly`)"
        }
      },
      "required": [
        "collaborator_id",
        "id",
        "starts_at",
        "start_time",
        "period",
        "is_approved",
        "is_locked"
      ],
      "description": "The details of the availability to be created."
    }
  }
}
Response  201
HideShow
Headers
Content-Type: application/json

Remove (un)availability
DELETE/api/v1/incoming/availabilities/{id}

Example URI

DELETE /api/v1/incoming/availabilities/1454
URI Parameters
HideShow
id
string (required) Example: 1454

The Beeple ID of the availability to be removed

Response  200
HideShow
Headers
Content-Type: application/json

Generated by aglio on 14 Oct 2021