Kantata Kantata OX Knowledge Base Release Notes Status Page
Kantata OX API Documentation

Events

Up to 7 days of trackable changes ("events") are recorded for an account and can be accessed via the Subscribed Events API. For a list of all the event types tracked by Subscribed Events, please see the Knowledge Base. Note that only Account Administrators can access Subscribed Events.

Some actions performed in Kantata OX can generate multiple events. For instance, approving an Expense Report will generate expense_report:updated and expense:updated events. Note that events for the same action are not guaranteed to appear in the exact order the changes were completed.

Also note that although we try to create events within a few minutes of an action being performed, events may take some time to appear.

Additionally, events may sometimes be duplicated. Your application should handle duplicate events appropriately.

Fetching a list of Subscribed Events

Returns up to 7 days of records for all event types, unless filter parameters have been applied.

Only records associated with the requester's Kantata OX account are returned.

This endpoint returns structured Subscribed Event objects. As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the results array and will be indexed by ID in the subscribed_events top-level JSON key. Please see our Response Format section for more information.

Request
query Parameters
created_after
string

Filter for events created after a specified datetime. Events may be generated out of order or the subject_changed_at and created_at times of an event can differ due to the lag between event occurrence and generation.

created_before
string

Filter for events created before a specified datetime. Events may be generated out of order or the subject_changed_at and created_at times of an event can differ due to the lag between event occurrence and generation.

event_types
string

Filter for records of specified event types. Specify multiple event types in a comma-separated list, like GET /api/v1/subscribed_events?event_types=time_entry:created,time_entry:updated,time_entry:deleted.

include
string

Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2.

  • subject (polymorphic) - When included, each event object will include a subject_ref that references the subject the event belongs to. The subject_ref is a JSON object with an id and key, where the key is the subject type.

For example, a workspace:updated event will have a subject_ref referencing the workspace, and the key will be workspaces.

If the subject is not available, subject_ref will be null. A subject may be unavailable if it was deleted or was transferred to another account.

most_recent
boolean

If true, only the most recent event will be returned for each subject (i.e. the most recent change that occurred for each subject).

most_recent_by_event_type
boolean

If true, only the most recent event of each event type will be returned for each subject.

For example, if a workspace was created, updated 3 times, and deleted, the following events will be generated: 1 workspace:created event, 3 workspace:updated events, and 1 workspace:deleted event. If most_recent_by_event_type is true, the workspace:created event, the most recent workspace:updated event, and the workspace:deleted event will be returned.

only
string

Allows you to request one or more resources directly by ID. Multiple IDs can be supplied in a comma separated list, like GET /api/v1/workspaces.json?only=5,6,7.

optional_fields
Array of strings

Allows you to request one or more optional fields as an array.

Items Enum: "previous_payload" "current_payload" "payload_changes"
order
string
Default: "subject_changed_at:desc"

Supply order with the name of a valid sort field for the endpoint and a direction.

Valid values: created_at:asc, created_at:desc, subject_changed_at:asc, and subject_changed_at:desc.

page
integer <int32>
Default: 1
per_page
integer <int32> <= 200
Default: 20
subject_changed_after
string

Filter for events where the event subject changed after a specified datetime.

subject_changed_before
string

Filter for events where the event subject changed before a specified datetime.

subject_id
string

Filter for events belonging to a specific subject (e.g. a user, a project, etc). When using this filter, you must also provide a subject_type. Multiple IDs can be provided in a comma-separated list (e.g. GET /api/v1/subscribed_events?subject_type=TimeEntry&subject_id=27,28,29).

subject_type
string

Filter for events by a specific subject type. You can pass in only one subject type for this parameter. Supported subject types: "AccountColor", "AccountLocation", "AccountMembership", "Assignment", "StoryAllocationDay", "EstimateScenario", "EstimateScenarioResource", "ExpenseReportSubmission", "Expense", "Participation", "Role", "Skill", "SkillMembership", "Story", "TimesheetSubmission", "TimeEntry", "User", "Vendor", "Workspace", "WorkspaceAllocation", "WorkspaceApprover", "WorkspaceGroup", "WorkspaceInvitation", "WorkspaceResource", "Estimate".

Responses
200

A list of Subscribed Events have been retrieved.

Response Schema: application/json
count
integer <int32>
object
Array of objects
object
400

Bad Request

401

Unauthorized request

403

Forbidden request

404

Page Not Found

422

Unprocessable Entity

503

Service is unavailable

get/subscribed_events
Request samples 
Response samples 
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "subscribed_events": {
    }
}
➔ Next to Account Locations