Congrats REST API

fields

An endpoint to manage the congrats fields.

Resource URL /rest/congrats/1.0/fields

Methods: GET POST

GET

Returns a list of all configured fields.

Response

{
    "status": 200,
    "data": [{
            "id": 1,
            "identifier": "birthday",
            "active": true,
            "systemfield": true,
            "name": "Birthday",
            "description": "What is your birthday?"
        }, {
            "id": 2,
            "identifier": "entrydate",
            "active": true,
            "systemfield": true,
            "name": "Date of entry",
            "description": "Your first day in our company."
        }],
    "success": true
}

POST

Parameters

Parameter	Type	Description
name	String	The (required) name of the new field
active	Boolean	Is the event active or inactive
description	String	The description of the event

Response

Returns all configured fields, including the new generated field.

{
    "status": 200,
    "data": [{
            "id": 1,
            "identifier": "birthday",
            "active": true,
            "systemfield": true,
            "name": "Birthday",
            "description": "What is your birthday?"
        }, {
            "id": 2,
            "identifier": "entrydate",
            "active": true,
            "systemfield": true,
            "name": "Date of entry",
            "description": "Your first day in our company."
        }, {
            "id": 3,
            "identifier": "1iv1j0oi0d4ro",
            "active": true,
            "systemfield": false,
            "name": "New field",
            "description": "My new field"
        }],
    "success": true
}

fields/values

Resource URL /rest/congrats/1.0/fields/values

Methods: GET

GET

A list of all fields with values, optional from a specific user.

Parameters

Parameter	Type	Description
active	Boolean	Is the field active or inactive
description	String	The description of the field
username	String	This parameter is optional. If set and the current logged in user is an administrator, this user is used. If the parameter empty, the current user is used.

Response

{
    "status": 200,
    "data": [{
            "id": 1,
            "identifier": "birthday",
            "active": true,
            "systemfield": true,
            "name": "Birthday",
            "description": "What is your birthday?",
            "value": "1981-07-25"
        }, {
            "id": 2,
            "identifier": "entrydate",
            "active": true,
            "systemfield": true,
            "name": "Date of entry",
            "description": "Your first day in our company.",
            "value": "2008-08-08"
        }],
    "success": true
}

fields/{id}

Resource URL /rest/congrats/1.0/fields/{id}

Methods: GET PUT DELETE

GET

Returns a field by the given id.

Parameters

Parameter	Type	Description
id	Long	The id of the field

Response

{
    "status": 200,
    "data": {
        "id": 1,
        "identifier": "birthday",
        "active": true,
        "systemfield": true,
        "name": "Birthday",
        "description": "What is your birthday?"
    },
    "success": true
}

PUT

Parameters

Parameter	Type	Description
id	Long	The (required) id of the field
name	String	The name of the field
active	Boolean	Is the field active or inactive
description	String	The description of the field

Response
Returns all configured fields, including the new generated field.

 {
    "status": 200,
    "data": [{
            "id": 1,
            "identifier": "birthday",
            "active": true,
            "systemfield": true,
            "name": "Birthday",
            "description": "What is your birthday?"
        }, {
            "id": 2,
            "identifier": "entrydate",
            "active": true,
            "systemfield": true,
            "name": "Date of entry",
            "description": "Your first day in our company."
        }, {
            "id": 3,
            "identifier": "1iv1j0oi0d4ro",
            "active": true,
            "systemfield": false,
            "name": "New field",
            "description": "My new field"
        }],
    "success": true
}

DELETE

Delete a field. This method needs to be authenticated by an administrator!

Parameters

Parameter	Type	Description
id	Long	The id of the field

Response
Status 200

fields/{id}/value

Resource URL /rest/congrats/1.0/fields/{id}/value

Methods: GET PUT POST DELETE

GET

Get the value of a field. Optional for a specific user.

Parameters

Parameter

Type

Description

id

Long

The id of the field

username

String

This parameter is optional. If set and the current logged in user is an admin, the given user is used.

If the parameter empty, the current user is used.

Response

{
    "status": 200,
    "data": {
        "id": 1,
        "identifier": "birthday",
        "active": true,
        "systemfield": true,
        "name": "Birthday",
        "description": "What is your birthday?",
        "value": "1981-07-25"
    },
    "success": true
}

PUT

Update the value of a field. Optional for a specific user.

Parameters

Parameter

Type

Description

id

Long

The (required) id of the field

username

String

This parameter is optional. If set and the current logged in user is an admin, the given user is used.

If the parameter empty, the current user is used.

date

String

The value for the field. This date has to be formatted in yyyy-mm-dd

Response

{
    "status": 200,
    "data": {
        "id": 1,
        "identifier": "birthday",
        "active": true,
        "systemfield": true,
        "name": "Birthday",
        "description": "What is your birthday?",
        "value": "1981-07-25"
    },
    "success": true
}

DELETE

Delete the value of corresponding field.

Parameters

Parameter	Type	Description
id	Long	The id of the field

Response
Status 200

POST

Update the value of a field. Optional for a specific user.

Parameters

Parameter

Type

Description

id

Long

The (required) id of the field

username

String

This parameter is optional. If set and the current logged in user is an admin, the given user is used.

If the parameter empty, the current user is used.

date

String

The value for the field. This date has to be formatted in yyyy-mm-dd

Response

{
    "status": 200,
    "data": {
        "id": 1,
        "identifier": "birthday",
        "active": true,
        "systemfield": true,
        "name": "Birthday",
        "description": "What is your birthday?",
        "value": "1981-07-25"
    },
    "success": true
}

events

Resource URL /rest/congrats/1.0/events

Methods: GET POST

GET

Returns the list of all events.

Response

{
    "status": 200,
    "data": [{
            "id": 1,
            "identifier": "birthday",
            "active": true,
            "systemfield": true,
            "name": "Birthday",
            "description": "",
            "runs": 0,
            "period": 0,
            "field": {
                "id": 1,
                "identifier": "birthday",
                "active": true,
                "systemfield": true,
                "name": "Birthday",
                "description": "What is your birthday?"
            }
        }, {
            "id": 2,
            "identifier": "entrydate",
            "active": true,
            "systemfield": true,
            "name": "Workplace anniversary",
            "description": "",
            "runs": 0,
            "period": 0,
            "field": {
                "id": 2,
                "identifier": "entrydate",
                "active": true,
                "systemfield": true,
                "name": "Date of entry",
                "description": "Your first day in our company."
            }
        }],
    "success": true
}

POST

Creates a new event. This method needs to be authenticated by an administrator!

Parameters

Parameter	Type	Description
name	String	The (required) name of the event
active	Boolean	Is the event active or inactive
fieldid	Long	The (required) field id
runs	Integer	How many time should the event run?
period	Integer	Weekly, monthly or yearly?
description	String	The description of the event

Response

The list of all events.

{
    "status": 200,
    "data": [{
            "id": 1,
            "identifier": "birthday",
            "active": true,
            "systemfield": true,
            "name": "Birthday",
            "description": "",
            "runs": 0,
            "period": 0,
            "field": {
                "id": 1,
                "identifier": "birthday",
                "active": true,
                "systemfield": true,
                "name": "Birthday",
                "description": "What is your birthday?"
            }
        }, {
            "id": 2,
            "identifier": "entrydate",
            "active": true,
            "systemfield": true,
            "name": "Workplace anniversary",
            "description": "",
            "runs": 0,
            "period": 0,
            "field": {
                "id": 2,
                "identifier": "entrydate",
                "active": true,
                "systemfield": true,
                "name": "Date of entry",
                "description": "Your first day in our company."
            }
        }],
    "success": true
}

events/active

Resource URL /rest/congrats/1.0/events/active

Methods: GET

GET

Returns the list of all active events.

Response

{
    "status": 200,
    "data": [{
            "id": 1,
            "identifier": "birthday",
            "active": true,
            "systemfield": true,
            "name": "Birthday",
            "description": "",
            "runs": 0,
            "period": 0,
            "field": {
                "id": 1,
                "identifier": "birthday",
                "active": true,
                "systemfield": true,
                "name": "Birthday",
                "description": "What is your birthday?"
            }
        }, {
            "id": 2,
            "identifier": "entrydate",
            "active": true,
            "systemfield": true,
            "name": "Workplace anniversary",
            "description": "",
            "runs": 0,
            "period": 0,
            "field": {
                "id": 2,
                "identifier": "entrydate",
                "active": true,
                "systemfield": true,
                "name": "Date of entry",
                "description": "Your first day in our company."
            }
        }],
    "success": true
}

events/{id}

Resource URL /rest/congrats/1.0/events/{id}

Methods: GET PUT DELETE

GET

Returns the event.

Parameters

Parameter	Type	Description
id	Long	The id of the event

Response

{
    "status": 200,
    "data": {
        "id": 1,
        "identifier": "birthday",
        "active": true,
        "systemfield": true,
        "name": "Birthday",
        "description": "",
        "runs": 0,
        "period": 0,
        "field": {
            "id": 1,
            "identifier": "birthday",
            "active": true,
            "systemfield": true,
            "name": "Birthday",
            "description": "What is your birthday?"
        }
    },
    "success": true
}

PUT

Updates a new event. All parameters (id excluded) are optional. This allows the user to update only specific values.This method needs to be authenticated by an administrator!

Parameters

Parameter	Type	Description
id	Long	The (required) event id
name	String	The (required) name of the event
active	Boolean	Is the event active or inactive
fieldid	Long	The (required) field id
runs	Integer	How many time should the event run?
period	Integer	Weekly, monthly or yearly?
description	String	The description of the event

Response

The list with all events.

{
    "status": 200,
    "data": [{
            "id": 1,
            "identifier": "birthday",
            "active": true,
            "systemfield": true,
            "name": "Birthday",
            "description": "",
            "runs": 0,
            "period": 0,
            "field": {
                "id": 1,
                "identifier": "birthday",
                "active": true,
                "systemfield": true,
                "name": "Birthday",
                "description": "What is your birthday?"
            }
        }, {
            "id": 2,
            "identifier": "entrydate",
            "active": true,
            "systemfield": true,
            "name": "Workplace anniversary",
            "description": "",
            "runs": 0,
            "period": 0,
            "field": {
                "id": 2,
                "identifier": "entrydate",
                "active": true,
                "systemfield": true,
                "name": "Date of entry",
                "description": "Your first day in our company."
            }
        }],
    "success": true
}

DELETE

Deteles an even the database. This method needs to be authenticated by an administrator!

Parameters

Parameter	Type	Description
id	Long	The id of the event

Response

Status 200

calendar

Resource URL /rest/congrats/1.0/calendar

Methods: GET

GET

Returns all calculated events in the given time frame.

Parameters

Parameter	Type	Description
events	Integer	The Id of the event(s) to be displayed (Comma separated).
maxEntries	Integer	The amount of returned entries.
startDate	String	The start date of the time frame. This date has to be formatted in `yyyy-mm-dd`
endDate	String	The end date of the time frameThis date has to be formatted in `yyyy-mm-dd`

Response

{
    "status": 200,
    "data": [{
            "dateFormatted": "Jun 24, 2016",
            "date": "2016-06-24",
            "event": {
                "id": 1,
                "name": "Birthday",
                "description": ""
            },
            "position": "Senior Developer",
            "iteration": 1,
            "user": {
                "avatarUrl": "/s/en_GB/6441/ceb41ce4dba5df18f2191c32f0465b43365a715a/_/download/attachments/3276808/user-avatar",
                "displayableEmail": "example@bitvoodoo.ch",
                "anonymous": false,
                "name": "test",
                "displayName": "Max Muster"
            },
            "alreadyNotified": false,
            "isHistory": true
        }, {
            "dateFormatted": "Jul 12, 2016",
            "date": "2016-07-12",
            "event": {
                "id": 2,
                "name": "Workplace anniversary",
                "description": ""
            },
            "position": "Senior Developer",
            "iteration": 1,
            "user": {
                "avatarUrl": "/s/en_GB/6441/ceb41ce4dba5df18f2191c32f0465b43365a715a/_/download/attachments/3276808/user-avatar",
                "displayableEmail": "example@bitvoodoo.ch",
                "anonymous": false,
                "name": "test",
                "displayName": "Max Muster"
            },
            "alreadyNotified": false,
            "isHistory": true
        }],
    "success": true
}

notifications

Resource URL rest/congrats/1.0/notifications

Methods: POST

POST

Returns all calculated events in the given time frame.

Parameters

Parameter	Type	Description
event	Integer	The Id of the event the notification is send for.
message	String	The congratulate message
date	String	The specific calculated event date in the format `yyyy-mm-dd`
username	String	The name of the receiver

Response
Status Code 200

fields

fields/values

fields/{id}

fields/{id}/value

events

events/active

events/{id}

calendar

notifications

Related articles