API Documentation

API Endpoint

Events

Events

Event resources represent Absence categories. More information about the Absence categories can be found in our Help documentation: Configuring Your Time Off Settings.

The /events endpoint allows you to create, update, delete, archive or unarchive (restore) Events.

The following diagram shows Events in our data hierarchy: Event diagram

For limited Events, absence bookings can only be created if the assignee has sufficient available hours or days defined via Entitlements. Approvers and subscribers for a Person’s absence booking on a specific Event can be managed through ApprovalWorkflows.

Also, we differentiate between time off (e.g. vacation, sick leave) and remote work (e.g. work from home) events. This is defined via the absence_type attribute. It is possible to change an event from the remote_work to the time_off absence type and vice versa, but please note that remote work events will always have the Unpaid event type.

For more details on how to work with remote work events, please refer to the Remote Work help article.

Supported attributes

  • name (string)

  • description (string)

  • color_id (integer) - defines the color of the corresponding absence bookings in Resourcing

  • icon_id (integer) - defines the icon used for the Person’s absence status

  • event_type_id (integer) - specifies whether an Event is Paid or Unpaid (has to be Unpaid for remote work events)

    • 1 (Paid)
    • 2 (Unpaid)

  • limitation_type_id (integer) - defines the type of Event’s limitation and the corresponding allocation type

    • 2 (Limited by days)
    • 3 (Limited by hours)
    • 4 (Unlimited)

  • half_day_bookings (boolean) - enables or disables half-day days bookings on Event

  • sync_personal_integrations (boolean) - controls whether the booking assignee’s absence status is synchronized with their external calendars and Slack

  • absence_type (string) - defines whether the event is intended for time off or remote work

    • time_off
    • remote_work

Supported filter params

  • id (integer)(array)

  • sync_personal_integrations (boolean)

  • half_day_bookings (boolean)

  • limited (boolean)

  • limitation_type (integer) (limited_by_days: 2, limited_by_hours: 3, unlimited: 4)

  • status (integer) (active: 1, archived: 2)

  • absence_type (string) (time_off, remote_work)

GET /api/v2/events
Requestsreturns events

GET  /api/v2/events

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "115",
      "type": "events",
      "attributes": {
        "name": "test name",
        "event_type_id": 2,
        "icon_id": null,
        "color_id": null,
        "archived_at": null,
        "limitation_type_id": 2,
        "sync_personal_integrations": true,
        "half_day_bookings": false,
        "description": null,
        "absence_type": "time_off"
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organizations",
            "id": "504"
          }
        }
      }
    },
    {
      "id": "116",
      "type": "events",
      "attributes": {
        "name": "test name",
        "event_type_id": 2,
        "icon_id": null,
        "color_id": null,
        "archived_at": null,
        "limitation_type_id": 2,
        "sync_personal_integrations": true,
        "half_day_bookings": false,
        "description": null,
        "absence_type": "remote_work"
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organizations",
            "id": "504"
          }
        }
      }
    },
    {
      "id": "114",
      "type": "events",
      "attributes": {
        "name": "Vacation",
        "event_type_id": 2,
        "icon_id": null,
        "color_id": null,
        "archived_at": null,
        "limitation_type_id": 2,
        "sync_personal_integrations": true,
        "half_day_bookings": false,
        "description": null,
        "absence_type": "time_off"
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organizations",
            "id": "504"
          }
        }
      }
    }
  ],
  "links": {
    "first": "http://api-test.productive.io/api/v2/events?page%5Bnumber%5D=1&page%5Bsize%5D=30",
    "last": "http://api-test.productive.io/api/v2/events?page%5Bnumber%5D=1&page%5Bsize%5D=30"
  },
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 3,
    "page_size": 30,
    "max_page_size": 200
  }
}

Get events
GET/api/v2/events

GET /api/v2/events/1
Requestsreturns event

GET  /api/v2/events/117

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "117",
    "type": "events",
    "attributes": {
      "name": "Vacation",
      "event_type_id": 2,
      "icon_id": null,
      "color_id": null,
      "archived_at": null,
      "limitation_type_id": 2,
      "sync_personal_integrations": true,
      "half_day_bookings": false,
      "description": null,
      "absence_type": "time_off"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "505"
        }
      }
    }
  },
  "meta": {}
}

Gets a event
GET/api/v2/events/{id}

URI Parameters
HideShow
id
number (required) Example: 1

event id

POST /api/v2/events
Requestscreates eventcreates event with half day absences enabledreturns error

POST  /api/v2/events

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "events",
    "attributes": {
      "name": "test name",
      "event_type_id": 2,
      "limitation_type_id": 4,
      "half_day_bookings": false,
      "absence_type": "time_off"
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "119",
    "type": "events",
    "attributes": {
      "name": "test name",
      "event_type_id": 2,
      "icon_id": null,
      "color_id": "1",
      "archived_at": null,
      "limitation_type_id": 4,
      "sync_personal_integrations": true,
      "half_day_bookings": false,
      "description": null,
      "absence_type": "time_off"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "506"
        }
      }
    }
  },
  "meta": {}
}

POST  /api/v2/events

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "events",
    "attributes": {
      "name": "test name",
      "event_type_id": 2,
      "limitation_type_id": 2,
      "half_day_bookings": true,
      "absence_type": "remote_work"
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "121",
    "type": "events",
    "attributes": {
      "name": "test name",
      "event_type_id": 2,
      "icon_id": null,
      "color_id": "1",
      "archived_at": null,
      "limitation_type_id": 2,
      "sync_personal_integrations": true,
      "half_day_bookings": true,
      "description": null,
      "absence_type": "remote_work"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "507"
        }
      }
    }
  },
  "meta": {}
}

POST  /api/v2/events

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "type": "events",
  "attributes": {
    "name": ""
  }
}
Responses422
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "status": "422",
      "code": "invalid_attribute",
      "title": "Invalid Attribute",
      "detail": "can't be blank",
      "source": {
        "pointer": "data/attributes/name"
      }
    },
    {
      "status": "422",
      "code": "invalid_attribute",
      "title": "Invalid Attribute",
      "detail": "can't be blank",
      "source": {
        "pointer": "data/attributes/event_type_id"
      }
    },
    {
      "status": "422",
      "code": "invalid_attribute",
      "title": "Invalid Attribute",
      "detail": "is not included in the list",
      "source": {
        "pointer": "data/attributes/event_type_id"
      }
    },
    {
      "status": "422",
      "code": "invalid_attribute",
      "title": "Invalid Attribute",
      "detail": "is not included in the list",
      "source": {
        "pointer": "data/attributes/limitation_type_id"
      }
    }
  ]
}

Create an event
POST/api/v2/events

URI Parameters
HideShow
name
string (required) Example: Name

name

event_type_id
number (required) Example: 1

event type id

limitation_type_id
id (required) Example: 4

limitation type (1 unlimited by days, 2 limited by days, 3 limited by hours, 4 unlimited by hours)

sync_personal_integrations
boolean (required) Example: true

marks if bookings for this event are being synced

half_day_bookings
boolean (optional) Example: true

marks if this event supports half day bookings

PATCH /api/v2/events/1
Requestsupdates eventreturns error

PATCH  /api/v2/events/123

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "events",
    "attributes": {
      "name": "new name"
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "123",
    "type": "events",
    "attributes": {
      "name": "new name",
      "event_type_id": 2,
      "icon_id": null,
      "color_id": "1",
      "archived_at": null,
      "limitation_type_id": 2,
      "sync_personal_integrations": true,
      "half_day_bookings": false,
      "description": null,
      "absence_type": "time_off"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "509"
        }
      }
    }
  },
  "meta": {}
}

PATCH  /api/v2/events/124

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "events",
    "attributes": {
      "name": ""
    }
  }
}
Responses422
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "status": "422",
      "code": "invalid_attribute",
      "title": "Invalid Attribute",
      "detail": "can't be blank",
      "source": {
        "pointer": "data/attributes/name"
      }
    }
  ]
}

Update an event
PATCH/api/v2/events/{id}

URI Parameters
HideShow
id
number (required) Example: 1

event id

PATCH /api/v2/events/1/archive
Requestsarchives eventarchives event

PATCH  /api/v2/events/126/archive

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "126",
    "type": "events",
    "attributes": {
      "name": "Vacation",
      "event_type_id": 2,
      "icon_id": null,
      "color_id": null,
      "archived_at": "2025-08-22T06:04:52.000+02:00",
      "limitation_type_id": 2,
      "sync_personal_integrations": true,
      "half_day_bookings": false,
      "description": null,
      "absence_type": "time_off"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "512"
        }
      }
    }
  },
  "meta": {}
}

PATCH  /api/v2/events/128/restore

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "128",
    "type": "events",
    "attributes": {
      "name": "test name",
      "event_type_id": 2,
      "icon_id": null,
      "color_id": null,
      "archived_at": null,
      "limitation_type_id": 2,
      "sync_personal_integrations": true,
      "half_day_bookings": false,
      "description": null,
      "absence_type": "time_off"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "513"
        }
      }
    }
  },
  "meta": {}
}

Archives an event
PATCH/api/v2/events/{id}/archive

URI Parameters
HideShow
id
number (required) Example: 1

event id

DELETE /api/v2/events/1
Requestsdeletes eventreturns error

DELETE  /api/v2/events/129

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Responses204
This response has no content.

DELETE  /api/v2/events/130

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Responses409
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "status": "409",
      "code": "record_not_archived",
      "title": "Conflict error",
      "source": {}
    }
  ]
}

Deletes an event
DELETE/api/v2/events/{id}

URI Parameters
HideShow
id
number (required) Example: 1

event id

Generated by aglio on 22 Aug 2025