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 linkedPOST/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
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652fBody
{
"collaborator": {
"first_name": "John",
"last_name": "Doe",
"beeple_id": 2403,
"external_id": "P77881",
"payroll_only": false,
"default_branch_id": 123,
"birth_date": "1995-05-07",
"birth_city": "Antwerpen",
"birth_country": "BE",
"gender": "male",
"language": "en",
"nationality": "BE",
"national_registration_numbers": [
{
"country": "BE",
"number": "YY.MM.DD-997.47"
}
],
"social_statute": "Arbeider",
"social_statute_code": "career_pause",
"home_address": {
"name": "Some Name",
"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",
"applies_to_all_departments": true,
"departments": [
{
"id": "101",
"name": "Acme Corp",
"description": "The department for Acme Corp"
}
]
},
"bank_account": {
"iban": "BE68539007547034",
"bic": "HBKABE22"
},
"blocked": false,
"blocked_by": {
"id": 2403,
"first_name": "John",
"last_name": "Doe",
"email": "John-doe@example.com"
},
"blocked_at": "2017-04-01T10:00:00.000+02:00",
"blocked_reason": "nothing to say",
"blocked_reason_remark": "nothing to say",
"blocked_reason_limited": "nothing to say",
"unblocked_by": {
"id": 2403,
"first_name": "John",
"last_name": "Doe",
"email": "John-doe@example.com"
},
"unblocked_at": "2017-04-01T10:00:00.000+02:00",
"rating": 2403,
"contact": {
"email": "john.doe@example.org",
"new_email": "john.doe@example.org",
"mobile": "+32498525251",
"phone": "+32498525251"
},
"departments": [
{
"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": {
"collaborator": {
"type": "object",
"properties": {
"first_name": {
"type": "string",
"description": "First name"
},
"last_name": {
"type": "string",
"description": "Last name"
},
"beeple_id": {
"type": "number",
"description": "Identification number within Beeple"
},
"external_id": {
"type": "string",
"description": "The identification that was attributed to the created collaborator"
},
"payroll_only": {
"type": "boolean",
"description": "Verify if payroll only is activated"
},
"default_branch_id": {
"type": "number",
"description": "The default branch id"
},
"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",
"description": "unique number format specified per person per country"
}
}
}
},
"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": {
"name": {
"type": "string",
"description": "The human name of the address"
},
"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"
},
"applies_to_all_departments": {
"type": "boolean",
"description": "If tenant uses department management, this property indicates whether address belongs to all departments of the tenant"
},
"departments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the client"
},
"name": {
"type": "string",
"description": "The name of the department"
},
"description": {
"type": "string",
"description": "A description of the department"
}
}
},
"description": "If tenant uses department management, this object lists departments of the address"
}
}
},
"bank_account": {
"type": "object",
"properties": {
"iban": {
"type": "string"
},
"bic": {
"type": "string"
}
}
},
"blocked": {
"type": "boolean",
"description": "Indicates if the user is blocked"
},
"blocked_by": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Identification number within Beeple"
},
"first_name": {
"type": "string",
"description": "First name"
},
"last_name": {
"type": "string",
"description": "Last name"
},
"email": {
"type": "string",
"description": "Email"
}
},
"required": [
"id",
"first_name",
"last_name"
],
"description": "The user who blocked the collaboraotr"
},
"blocked_at": {
"type": "string",
"description": "Indicates when the user was blocked if blocked"
},
"blocked_reason": {
"type": "string",
"description": "A comment posted during block or unblock"
},
"blocked_reason_remark": {
"type": "string",
"description": "A comment posted during block or unblock as a remark"
},
"blocked_reason_limited": {
"type": "string",
"description": "A comment posted during block or unblock as a reason limited"
},
"unblocked_by": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Identification number within Beeple"
},
"first_name": {
"type": "string",
"description": "First name"
},
"last_name": {
"type": "string",
"description": "Last name"
},
"email": {
"type": "string",
"description": "Email"
}
},
"required": [
"id",
"first_name",
"last_name"
],
"description": "The user who unblocked the collaboraotr"
},
"unblocked_at": {
"type": "string",
"description": "Indicates when the user was unblocked if unblocked"
},
"rating": {
"type": "number",
"description": "Indicates the collaborators rating"
},
"contact": {
"type": "object",
"properties": {
"email": {
"type": "string"
},
"new_email": {
"type": "string"
},
"mobile": {
"type": "string"
},
"phone": {
"type": "string"
}
},
"required": [
"email"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the department"
}
}
},
"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",
"beeple_id",
"default_branch_id",
"language",
"primary_department_id",
"primary_manager_id"
]
}
}
}Response
200Headers
Content-Type: application/jsonBody
{
"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
200Headers
Content-Type: application/jsonResponse
400Headers
Content-Type: application/jsonBody
{
"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 updatedPATCH/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
- beeple_id
string(required) Example: 1454The Beeple ID of the collaborator
Request
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652fBody
{
"collaborator": {
"first_name": "John",
"last_name": "Doe",
"beeple_id": 2403,
"external_id": "P77881",
"payroll_only": false,
"default_branch_id": 123,
"birth_date": "1995-05-07",
"birth_city": "Antwerpen",
"birth_country": "BE",
"gender": "male",
"language": "en",
"nationality": "BE",
"national_registration_numbers": [
{
"country": "BE",
"number": "YY.MM.DD-997.47"
}
],
"social_statute": "Arbeider",
"social_statute_code": "career_pause",
"home_address": {
"name": "Some Name",
"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",
"applies_to_all_departments": true,
"departments": [
{
"id": "101",
"name": "Acme Corp",
"description": "The department for Acme Corp"
}
]
},
"bank_account": {
"iban": "BE68539007547034",
"bic": "HBKABE22"
},
"blocked": false,
"blocked_by": {
"id": 2403,
"first_name": "John",
"last_name": "Doe",
"email": "John-doe@example.com"
},
"blocked_at": "2017-04-01T10:00:00.000+02:00",
"blocked_reason": "nothing to say",
"blocked_reason_remark": "nothing to say",
"blocked_reason_limited": "nothing to say",
"unblocked_by": {
"id": 2403,
"first_name": "John",
"last_name": "Doe",
"email": "John-doe@example.com"
},
"unblocked_at": "2017-04-01T10:00:00.000+02:00",
"rating": 2403,
"contact": {
"email": "john.doe@example.org",
"new_email": "john.doe@example.org",
"mobile": "+32498525251",
"phone": "+32498525251"
},
"departments": [
{
"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": {
"collaborator": {
"type": "object",
"properties": {
"first_name": {
"type": "string",
"description": "First name"
},
"last_name": {
"type": "string",
"description": "Last name"
},
"beeple_id": {
"type": "number",
"description": "Identification number within Beeple"
},
"external_id": {
"type": "string",
"description": "The identification that was attributed to the created collaborator"
},
"payroll_only": {
"type": "boolean",
"description": "Verify if payroll only is activated"
},
"default_branch_id": {
"type": "number",
"description": "The default branch id"
},
"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",
"description": "unique number format specified per person per country"
}
}
}
},
"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": {
"name": {
"type": "string",
"description": "The human name of the address"
},
"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"
},
"applies_to_all_departments": {
"type": "boolean",
"description": "If tenant uses department management, this property indicates whether address belongs to all departments of the tenant"
},
"departments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the client"
},
"name": {
"type": "string",
"description": "The name of the department"
},
"description": {
"type": "string",
"description": "A description of the department"
}
}
},
"description": "If tenant uses department management, this object lists departments of the address"
}
}
},
"bank_account": {
"type": "object",
"properties": {
"iban": {
"type": "string"
},
"bic": {
"type": "string"
}
}
},
"blocked": {
"type": "boolean",
"description": "Indicates if the user is blocked"
},
"blocked_by": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Identification number within Beeple"
},
"first_name": {
"type": "string",
"description": "First name"
},
"last_name": {
"type": "string",
"description": "Last name"
},
"email": {
"type": "string",
"description": "Email"
}
},
"required": [
"id",
"first_name",
"last_name"
],
"description": "The user who blocked the collaboraotr"
},
"blocked_at": {
"type": "string",
"description": "Indicates when the user was blocked if blocked"
},
"blocked_reason": {
"type": "string",
"description": "A comment posted during block or unblock"
},
"blocked_reason_remark": {
"type": "string",
"description": "A comment posted during block or unblock as a remark"
},
"blocked_reason_limited": {
"type": "string",
"description": "A comment posted during block or unblock as a reason limited"
},
"unblocked_by": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Identification number within Beeple"
},
"first_name": {
"type": "string",
"description": "First name"
},
"last_name": {
"type": "string",
"description": "Last name"
},
"email": {
"type": "string",
"description": "Email"
}
},
"required": [
"id",
"first_name",
"last_name"
],
"description": "The user who unblocked the collaboraotr"
},
"unblocked_at": {
"type": "string",
"description": "Indicates when the user was unblocked if unblocked"
},
"rating": {
"type": "number",
"description": "Indicates the collaborators rating"
},
"contact": {
"type": "object",
"properties": {
"email": {
"type": "string"
},
"new_email": {
"type": "string"
},
"mobile": {
"type": "string"
},
"phone": {
"type": "string"
}
},
"required": [
"email"
]
},
"departments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the department"
}
}
},
"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",
"beeple_id",
"default_branch_id",
"language",
"primary_department_id",
"primary_manager_id"
]
}
}
}Response
200Headers
Content-Type: application/jsonResponse
400Headers
Content-Type: application/jsonBody
{
"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 unlinkedDELETE/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
- beeple_id
string(required) Example: 1454The Beeple ID of the collaborator
- company_id
string(required) Example: ddde1555-9bb6-4180-91f4-db063f54c9c8The ID of the tenant. A UUID which will not change.
Request
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652fResponse
200Headers
Content-Type: application/jsonResponse
204Headers
Content-Type: application/jsonCollaborator 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 collaboratorPOST/api/v1/incoming/collaborators
Example URI
POST /api/v1/incoming/collaborators
Request
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652fBody
{
"name": "John Doe",
"id": 2403,
"email": "john.doe@example.org",
"mobile": "+32498525251",
"gender": "male",
"nationality": "BE",
"social_statute_code": "career_pause",
"national_registration_numbers": [
{
"country": "BE",
"number": "YY.MM.DD-997.47"
}
],
"language": "en",
"birth_date": "1995-05-07",
"birth_place": "Antwerpen",
"birth_country": "BE",
"contact_person": {
"email": "john.doe@example.org",
"mobile": "+32498525251"
},
"iban": "BE68539007547034",
"bic": "HBKABE22",
"primary_address": {
"name": "Some Name",
"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",
"applies_to_all_departments": true,
"departments": [
{
"id": "101",
"name": "Acme Corp",
"description": "The department for Acme Corp"
}
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the collaborator"
},
"id": {
"type": "number",
"description": "Identification number within Beeple"
},
"email": {
"type": "string",
"description": "Email of the collaborator"
},
"mobile": {
"type": "string",
"description": "Phone number of the collaborator"
},
"gender": {
"type": "string",
"enum": [
"male",
"female"
],
"description": "Gender"
},
"nationality": {
"type": "string",
"description": "According to ISO 3166-1 alpha-2"
},
"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"
},
"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",
"description": "unique number format specified per person per country"
}
}
}
},
"language": {
"type": "string",
"description": "Language in which to communicate with the collaborator according to ISO 639-1"
},
"birth_date": {
"type": "string",
"description": "Birth date according RFC 3339"
},
"birth_place": {
"type": "string",
"description": "Birth city"
},
"birth_country": {
"type": "string",
"description": "Birth country according to ISO 3166-1 alpha-2"
},
"contact_person": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "The email of this contact person"
},
"mobile": {
"type": "string",
"description": "The phone number"
}
},
"required": [
"email"
],
"description": "A contact person in case of emergency"
},
"iban": {
"type": "string",
"description": "IBAN number"
},
"bic": {
"type": "string",
"description": "BIC number"
},
"primary_address": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The human name of the address"
},
"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"
},
"applies_to_all_departments": {
"type": "boolean",
"description": "If tenant uses department management, this property indicates whether address belongs to all departments of the tenant"
},
"departments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the client"
},
"name": {
"type": "string",
"description": "The name of the department"
},
"description": {
"type": "string",
"description": "A description of the department"
}
}
},
"description": "If tenant uses department management, this object lists departments of the address"
}
},
"description": "The home address"
}
},
"required": [
"name",
"id",
"language"
]
}Response
200Headers
Content-Type: application/jsonContract requests ¶
List of Contracts ¶
Request contractPOST/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
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652fBody
{
"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": {
"name": "Some Name",
"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",
"applies_to_all_departments": true,
"departments": [
{
"id": "101",
"name": "Acme Corp",
"description": "The department for Acme Corp"
}
],
"latlon_lat": "45.2222",
"latlon_lon": "15.2222",
"latlon_applied_manually": true,
"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": {
"name": {
"type": "string",
"description": "The human name of the address"
},
"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"
},
"applies_to_all_departments": {
"type": "boolean",
"description": "If tenant uses department management, this property indicates whether address belongs to all departments of the tenant"
},
"departments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the client"
},
"name": {
"type": "string",
"description": "The name of the department"
},
"description": {
"type": "string",
"description": "A description of the department"
}
}
},
"description": "If tenant uses department management, this object lists departments of the address"
},
"latlon_lat": {
"type": "string",
"description": "Latitude of the address"
},
"latlon_lon": {
"type": "string",
"description": "Longitude of the address"
},
"latlon_applied_manually": {
"type": "boolean",
"description": "this should only be set to true if the geo_coordinates are set manually by the user"
},
"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
200Headers
Content-Type: application/jsonBody
{
"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
202Headers
Content-Type: application/jsonResponse
400Headers
Content-Type: application/jsonBody
{
"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 contractDELETE/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
- contractid
string(required) Example: 87643The Beeple ID of the contract that needs to be cancelled
Request
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652fBody
{
"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
200Headers
Content-Type: application/jsonResponse
202Headers
Content-Type: application/jsonContract Callback ¶
Updates & CancellationPATCH/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
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652fBody
{
"contract": {
"beeple_id": 87643,
"external_id": "C197654",
"collaborator": {
"beeple_id": 2403,
"external_id": "P77881"
},
"status": "approved",
"work_station_address": {
"name": "Some Name",
"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",
"applies_to_all_departments": true,
"departments": [
{
"id": "101",
"name": "Acme Corp",
"description": "The department for Acme Corp"
}
],
"addition": "At the entrance"
}
},
"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": {
"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"
]
},
"work_station_address": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The human name of the address"
},
"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"
},
"applies_to_all_departments": {
"type": "boolean",
"description": "If tenant uses department management, this property indicates whether address belongs to all departments of the tenant"
},
"departments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the client"
},
"name": {
"type": "string",
"description": "The name of the department"
},
"description": {
"type": "string",
"description": "A description of the department"
}
}
},
"description": "If tenant uses department management, this object lists departments of the address"
},
"addition": {
"type": "string",
"description": "Specific location where the collaborator was planed to work"
}
},
"description": "Where the collaborator was planned to work"
}
},
"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
200Headers
Content-Type: application/jsonCosts ¶
Costs ¶
Report costsPOST/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
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652fBody
{
"company": {
"name": "My company",
"beeple_id": "273e949a-bb41-4f36-9526-d1d0a8043c91",
"enterprise_number": "0101010101",
"payroll_service_id": "5"
},
"contract": {
"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": {
"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
200Headers
Content-Type: application/jsonUnplanned Costs ¶
Report unplanned costsPOST/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
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652fBody
{
"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
200Headers
Content-Type: application/jsonHour registration ¶
Worked hours ¶
Report worked hoursPOST/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
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652fBody
{
"company": {
"name": "My company",
"beeple_id": "273e949a-bb41-4f36-9526-d1d0a8043c91",
"enterprise_number": "0101010101",
"payroll_service_id": "5"
},
"contract": {
"beeple_id": 87643,
"collaborator": {
"id": 2403,
"first_name": "John",
"last_name": "Doe",
"email": "John-doe@example.com"
},
"project": {
"beeple_id": 31324,
"name": "Example Project",
"description": "Description of example project",
"start_date": "2017-08-15",
"end_date": "2017-09-15",
"published": true
},
"subproject": {
"beeple_id": 12412,
"name": "Example subproject"
},
"team": {
"beeple_id": 34513,
"name": "Example Team"
},
"shift": {
"beeple_id": 39512,
"start_datetime": "2022-07-01T10:00:00Z",
"end_datetime": "2022-07-01T15:00:00Z",
"break_duration": "01:00"
}
},
"worked_hours": {
"beeple_id": 87643,
"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",
"confirmed_by": {
"id": 2403,
"first_name": "John",
"last_name": "Doe",
"email": "John-doe@example.com"
}
}
}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": "number",
"description": "Identification number within Beeple"
},
"collaborator": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Identification number within Beeple"
},
"first_name": {
"type": "string",
"description": "First name"
},
"last_name": {
"type": "string",
"description": "Last name"
},
"email": {
"type": "string",
"description": "Email"
}
},
"required": [
"id",
"first_name",
"last_name"
],
"description": "Collaborator of the contract"
},
"project": {
"type": "object",
"properties": {
"beeple_id": {
"type": "number",
"description": "Identification number within Beeple"
},
"name": {
"type": "string",
"description": "The name of the project (max 255 characters)"
},
"description": {
"type": "string",
"description": "A description of the project"
},
"start_date": {
"type": "string",
"description": "Start date of the project in YYYY-MM-DD"
},
"end_date": {
"type": "string",
"description": "End date of the project in YYYY-MM-DD"
},
"published": {
"type": "boolean",
"description": "Indication whether the project is published"
}
},
"required": [
"beeple_id",
"name",
"description",
"start_date",
"end_date",
"published"
],
"description": "project info"
},
"subproject": {
"type": "object",
"properties": {
"beeple_id": {
"type": "number",
"description": "Identification number within Beeple"
},
"name": {
"type": "string",
"description": "The name of the subproject"
}
},
"required": [
"beeple_id",
"name"
],
"description": "subproject info"
},
"team": {
"type": "object",
"properties": {
"beeple_id": {
"type": "number",
"description": "Identification number within Beeple"
},
"name": {
"type": "string",
"description": "The name of the team"
}
},
"required": [
"beeple_id",
"name"
],
"description": "team info"
},
"shift": {
"type": "object",
"properties": {
"beeple_id": {
"type": "number",
"description": "Identification number within Beeple"
},
"start_datetime": {
"type": "string",
"description": "A start time of the shift in ISO 8601 format"
},
"end_datetime": {
"type": "string",
"description": "An end time of the shift in ISO 8601 format"
},
"break_duration": {
"type": "string",
"description": "Duration of shift's break"
}
},
"required": [
"beeple_id",
"start_datetime",
"end_datetime",
"break_duration"
],
"description": "shift info"
}
},
"required": [
"beeple_id"
],
"description": "Contract for which worked hours are reported"
}
},
"oneOf": [
{
"properties": {
"worked_hours": {
"type": "object",
"properties": {
"beeple_id": {
"type": "number",
"description": "Identification number within Beeple"
},
"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."
},
"confirmed_by": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Identification number within Beeple"
},
"first_name": {
"type": "string",
"description": "First name"
},
"last_name": {
"type": "string",
"description": "Last name"
},
"email": {
"type": "string",
"description": "Email"
}
},
"required": [
"id",
"first_name",
"last_name"
],
"description": "The collaborator who confirmed worked hour"
}
},
"required": [
"beeple_id",
"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
200Headers
Content-Type: application/jsonUnplanned 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/absencesPOST/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
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652fBody
{
"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": {
"beeple_id": 87643,
"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",
"confirmed_by": {
"id": 2403,
"first_name": "John",
"last_name": "Doe",
"email": "John-doe@example.com"
}
}
}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": {
"beeple_id": {
"type": "number",
"description": "Identification number within Beeple"
},
"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."
},
"confirmed_by": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Identification number within Beeple"
},
"first_name": {
"type": "string",
"description": "First name"
},
"last_name": {
"type": "string",
"description": "Last name"
},
"email": {
"type": "string",
"description": "Email"
}
},
"required": [
"id",
"first_name",
"last_name"
],
"description": "The collaborator who confirmed worked hour"
}
},
"required": [
"beeple_id",
"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
200Headers
Content-Type: application/jsonAvailabilities ¶
List of Availabilities ¶
Create (un)availabilitiesPOST/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
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652fBody
{
"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",
"uploaded_by": {
"id": 2403,
"first_name": "John",
"last_name": "Doe",
"email": "John-doe@example.com"
},
"uploaded_at": "2020-04-01T19:05: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 (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"
},
"uploaded_by": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Identification number within Beeple"
},
"first_name": {
"type": "string",
"description": "First name"
},
"last_name": {
"type": "string",
"description": "Last name"
},
"email": {
"type": "string",
"description": "Email"
}
},
"required": [
"id",
"first_name",
"last_name"
],
"description": "The user who created the piece of evidence"
},
"uploaded_at": {
"type": "string",
"description": "the time stamp when the counter event was recorded according RFC 3339."
}
},
"required": [
"uploaded_at"
]
},
"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
200Headers
Content-Type: application/jsonUpdate (un)availabilityPATCH/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
- id
string(required) Example: 1454The Beeple ID of the availability
Request
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652fBody
{
"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",
"uploaded_by": {
"id": 2403,
"first_name": "John",
"last_name": "Doe",
"email": "John-doe@example.com"
},
"uploaded_at": "2020-04-01T19:05: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 (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"
},
"uploaded_by": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Identification number within Beeple"
},
"first_name": {
"type": "string",
"description": "First name"
},
"last_name": {
"type": "string",
"description": "Last name"
},
"email": {
"type": "string",
"description": "Email"
}
},
"required": [
"id",
"first_name",
"last_name"
],
"description": "The user who created the piece of evidence"
},
"uploaded_at": {
"type": "string",
"description": "the time stamp when the counter event was recorded according RFC 3339."
}
},
"required": [
"uploaded_at"
]
},
"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
200Headers
Content-Type: application/jsonRemove (un)availabilityDELETE/availabilities/{id}
Sent if the availability is deleted in Beeple before it has been approved or rejected.
Example URI
DELETE /availabilities/1454
URI Parameters
- id
string(required) Example: 1454The Beeple ID of the availability
Request
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652fResponse
200Headers
Content-Type: application/jsonOne 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 loginPOST/one-time-login
Example URI
POST /one-time-login
Request
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652fBody
{
"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
200Headers
Content-Type: application/jsonBody
{
"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 notificationPOST/api/v1/incoming/notifications
Example URI
POST /api/v1/incoming/notifications
Request
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652fBody
{
"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
201Headers
Content-Type: application/jsonExternally created Availabilities ¶
Availabilities ¶
A payroll integration may call this endpoint to create or remove collaborators availabilities in the Beeple Web applicatioon.
Create availabilityPOST/api/v1/incoming/availabilities
Example URI
POST /api/v1/incoming/availabilities
Request
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652fBody
{
"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,
"permissions": {
"can_update": true,
"can_destroy": true,
"can_approve": true
},
"approvers": [
"John Bossman",
"Mary Highness"
],
"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"
},
"permissions": {
"type": "object",
"properties": {
"can_update": {
"type": "boolean",
"description": "When true, the calling user can update the availability record"
},
"can_destroy": {
"type": "boolean",
"description": "When true, the calling user can delete the availability record"
},
"can_approve": {
"type": "boolean",
"description": "When true, the calling user can approve the availability record (only valid if the AV type requires approval)"
}
},
"description": "A detail of actions that can be performed on the availability record by the calling user"
},
"approvers": {
"type": "array",
"description": "a list of names of users that can approve 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",
"permissions"
],
"description": "The details of the availability to be created."
}
}
}Response
201Headers
Content-Type: application/jsonRemove (un)availabilityDELETE/api/v1/incoming/availabilities/{id}
Example URI
DELETE /api/v1/incoming/availabilities/1454
URI Parameters
- id
string(required) Example: 1454The Beeple ID of the availability to be removed
Response
200Headers
Content-Type: application/json