developers API Documentation

Calendar Entries are items on a calendar, and can be associated to deals, people, or companies.

Important Note

There are two different, separate types of calendar entries: Tasks and events

Events:

  • Have a defined start time and end time, both of which are required for the event to be valid.

Tasks:

  • Have only a due date, which is a calendar date, and has no time. The due date is optional

Calendar Entry Attributes

Name Type Default val Example Writable? Description
id integer 1234 no the entry's unique identifier
type string CalendarEvent yes Required. The entry type. Specify CalendarEvent for events, and CalendarTask for tasks.
owner_id integer 1234 no The user id of who owns the event. You can retrieve a list of users using the users api.
owner object {id: 456, full_name: 'Bob Smith'} no Convenience method to access the owner id and full name.
category_id integer 1234 yes The event category. You can retrieve a list of event categories using the event categories api.
category object {id: 456, name: 'Phone call'} no (to change the category, use category_id) Convenience object to access the category name for the entry
name string Call with bob yes The name of the event
description string The meeting is at 3:30 yes A more detailed description of the event
start_time datetime 2012-06-13 11:47:15(time zone is user's time zone) yes CalendarEvents only. Specify the start_time for the event.
end_time datetime 2012-06-13 11:47:15(time zone is user's time zone) yes CalendarEvents only. Specify the end time for the event.
all_day boolean Events: false, Tasks: true false yes Specify that this event is all day
due_date date 2011-01-01 yes Tasks only. Specify the due date.
complete boolean false yes complete or not.
completed_at datetime 2012-06-13 11:47:15(time zone is user's time zone) no Timestamp for when the complete flag was set to true
association_id integer 1234 yes The id of the associated person, company, or deal
association_type string Deal yes The type of association. will be Deal, Company, or Person.
base_entry_id integer 1234 no If the event is part of a recurring series, this points to the base entry of the recurring series.
active boolean true yes Inactive events are functionally equivalent to deleted events. Events that are part of a series, when deleted by a user, are instead marked inactive
created_at datetime 2012-06-13 11:47:15(time zone is user's time zone) yes Timestamp for when the entry was created
updated_at datetime 2012-06-13 11:47:15(time zone is user's time zone) yes Timestamp for when the entry was last touched
google_calendar_id string abcd1234 no This is no longer used, but provided for backwards compatibility purposes.
company_id integer 1234 yes If this event is tied directly with a company, then this will be set to the company id.
rrule string FREQ=WEEKLY;BYDAY=TU yes Specify an rrule to change the recurrence rule. This string follows the iCalendar spec, RFC2445.
rdate string yes Specify an rdate to change the recurrence rule. This string follows the iCalendar spec, RFC2445.
exrule string yes Specify an exrule to change the recurrence rule. This string follows the iCalendar spec, RFC2445.
exdate string yes Specify an exdate to change the recurrence rule. This string follows the iCalendar spec, RFC2445.
part_of_recurring_series boolean false no Convenience method to see if an event is part of a recurring series.
recurrence_end date 2011-01-01 no Convenience method to get the recurrence end date

Receive a list of Calendar Events

Request format

GET /calendar_entries.json

Request Parameters

Param Type Description
page integer The page offest.
per_page integer The number of calendar entries per page.
search_id integer Search calendar entries by previously saved filter with given search_id. Note: when you provide a search_id, all parameters except page and per_page will be ignored.
sort string Calendar entries accept the following sorts: due_date, -due_date, start_time, -start_time, created_at, -created_at, updated_at, -updated_at
conditions[named] String Select only calendar entries with a name matching the exact string given.
conditions[kind] string Whether you want to return only tasks or only events. Must be either task or event. Leave out for both.
conditions[owner_id] integer The calendar entries that are owned by owner_id
conditions[completed]=true boolean Return only completed events
conditions[incomplete]=true boolean Return only incomplete events
conditions[late]=true boolean Return only late items
conditions[today]=true boolean Return items due today
conditions[tomorrow]=true boolean Return items due tomorrow
conditions[this_week]=true boolean Return items due this week
conditions[next_week]=true boolean Return items due next week
conditions[future]=true boolean Return items due after next week
conditions[within][from_date] datetime The calendar entries that occur within the start and end time provided.
conditions[within][to_date] datetime Paired with conditions[within][start]
conditions[starting_at] String Select calendar entries matching the exact start time given. Most datetime formats will be parsed correctly.
conditions[ending_at] String Select calendar entries matching the exact end time given. Most datetime formats will be parsed correctly.
conditions[someday] boolean Return calendar tasks with no due date.
conditions[recurrences_of] integer Pass in the id of the base event in a series, and get all other events in the series.
conditions[non_recurring] anything, always treats the value as true Return only events that aren't part of a series.
conditions[base_entries] anything, always treats the value as true Return only events that are the first (base) event in a series.
conditions[include_inactive] anything, always treats the value as true Return entries marked as 'inactive', which are functionally equivalent to being deleted. Events that are part of a series that are deleted are actually just marked inactive, so that the entire series can be replicated accurately on other systems.
conditions[calendar_entry_modified] qualify a search using updated_at You can pass in a datetime range to qualify searches based upon the calendar entry's updated_at field.

Examples

curl -v -X POST -H "Accept: application/json" -H "Content-type: application/json" https://api.pipelinedeals.com/api/v3/calendar_entries.json?api_key=abc1234      
HTTP Code
200
Body
{
  "pagination":{
    "total":50,
    "per_page":1,
    "page":1
  },
  "entries":[
    {
      "exdate":null,
      "due_date":"2012/01/20",
      "completed_at":null,
      "company_id":4,
      "base_entry_id":null,
      "type":"CalendarTask",
      "start_time":null,
      "id":1,
      "end_time":null,
      "all_day":true,
      "part_of_recurring_series":false,
      "updated_at":"2012/01/19 15:26:09 -0500",
      "exrule":null,
      "complete":false,
      "association_id":1,
      "rrule":null,
      "description":null,
      "category":{"id":2,"name":"Call"},
      "owner_id":1,
      "name":"Introductory Call",
      "created_at":"2012/01/19 15:26:09 -0500",
      "category_id":2,
      "owner":{"id":1,"full_name":"admin nick"},
      "association_type":"Deal",
      "recurrence_end":null,
      "google_calendar_id":null,
      "rdate":null
    }
  ]
}

Create a Calendar Entry

Request format

POST /calendar_entries.json

Examples

curl -H "Accept: application/json" -X POST -d "calendar_entry[type]=CalendarTask&calendar_entry[due_date]=2013-01-01&calendar_entry[name]=Happy new year" \
  "https://api.pipelinedeals.com/api/v3/calendar_entries.json?api_key=abc1234"
HTTP Code
200
Body
{
  "all_day": true, 
  "association_id": 2, 
  "association_type": "Deal", 
  "category": {
      "id": 2, 
      "name": "Call"
  }, 
  "category_id": 2,
  "company_id": null, 
  "complete": true, 
  "completed_at": "2011/10/12 10:03:59 -0400", 
  "created_at": "2011/10/12 10:03:59 -0400", 
  "description": null, 
  "due_date": "2011/10/13", 
  "end_time": null, 
  "google_calendar_id": null, 
  "id": 1, 
  "name": "Introductory Call", 
  "owner_id": 1,
  "base_entry_id": null,
  "owner": {
      "full_name": "Benjamin Rhodes", 
      "id": 1
  }, 
  "part_of_recurring_series": false, 
  "rrule": null,
  "rdate": null,
  "exrule": null,
  "exdate": null,
  "recurrence_end": null, 
  "start_time": null, 
  "type": "CalendarTask", 
  "updated_at": "2011/10/14 12:30:19 -0400"
  "all_day": true, 
  "association_id": 2, 
  "association_type": "Deal", 
  "category": {
      "id": 2, 
      "name": "Call"
  }, 
  "category_id": 2,
  "company_id": null, 
  "complete": true, 
  "completed_at": "2011/10/12 10:03:59 -0400", 
  "created_at": "2011/10/12 10:03:59 -0400", 
  "description": null, 
  "due_date": "2011/10/13", 
  "end_time": null, 
  "google_calendar_id": null, 
  "id": 1, 
  "name": "Introductory Call", 
  "owner_id": 1,
  "base_entry_id": null,
  "owner": {
      "full_name": "Benjamin Rhodes", 
      "id": 1
  }, 
  "part_of_recurring_series": false, 
  "rrule": null,
  "rdate": null,
  "exrule": null,
  "exdate": null,
  "recurrence_end": null, 
  "start_time": null, 
  "type": "CalendarTask", 
  "updated_at": "2011/10/14 12:30:19 -0400"
}

Retrieve a calendar entry

Request format

GET /calendar_entries/:id.json

Examples

curl "https://api.pipelinedeals.com/api/v3/calendar_entries/15151.json?api_key=abc1234"
HTTP Code
200
Body
{
  "all_day": true, 
  "association_id": 2, 
  "association_type": "Deal", 
  "category": {
      "id": 2, 
      "name": "Call"
  }, 
  "category_id": 2,
  "company_id": null, 
  "complete": true, 
  "completed_at": "2011/10/12 10:03:59 -0400", 
  "created_at": "2011/10/12 10:03:59 -0400", 
  "description": null, 
  "due_date": "2011/10/13", 
  "end_time": null, 
  "google_calendar_id": null, 
  "id": 1, 
  "name": "Introductory Call", 
  "owner_id": 1,
  "base_entry_id": null,
  "owner": {
      "full_name": "Benjamin Rhodes", 
      "id": 1
  }, 
  "part_of_recurring_series": false, 
  "rrule": null,
  "rdate": null,
  "exrule": null,
  "exdate": null,
  "recurrence_end": null, 
  "start_time": null, 
  "type": "CalendarTask", 
  "updated_at": "2011/10/14 12:30:19 -0400"
  "all_day": true, 
  "association_id": 2, 
  "association_type": "Deal", 
  "category": {
      "id": 2, 
      "name": "Call"
  }, 
  "category_id": 2,
  "company_id": null, 
  "complete": true, 
  "completed_at": "2011/10/12 10:03:59 -0400", 
  "created_at": "2011/10/12 10:03:59 -0400", 
  "description": null, 
  "due_date": "2011/10/13", 
  "end_time": null, 
  "google_calendar_id": null, 
  "id": 1, 
  "name": "Introductory Call", 
  "owner_id": 1,
  "base_entry_id": null,
  "owner": {
      "full_name": "Benjamin Rhodes", 
      "id": 1
  }, 
  "part_of_recurring_series": false, 
  "rrule": null,
  "rdate": null,
  "exrule": null,
  "exdate": null,
  "recurrence_end": null, 
  "start_time": null, 
  "type": "CalendarTask", 
  "updated_at": "2011/10/14 12:30:19 -0400"
}

Update a calendar entry

Request format

PUT /calendar_entries/:id.json

Examples

curl -H "Accept: application/json" -X PUT -d "calendar_entry[name]=update the task" \
  "https://api.pipelinedeals.com/api/v3/calendar_entries/15151.json?api_key=abc1234"
HTTP Code
200
Body
{
  "all_day": true, 
  "association_id": 2, 
  "association_type": "Deal", 
  "category": {
      "id": 2, 
      "name": "Call"
  }, 
  "category_id": 2,
  "company_id": null, 
  "complete": true, 
  "completed_at": "2011/10/12 10:03:59 -0400", 
  "created_at": "2011/10/12 10:03:59 -0400", 
  "description": null, 
  "due_date": "2011/10/13", 
  "end_time": null, 
  "google_calendar_id": null, 
  "id": 1, 
  "name": "Introductory Call", 
  "owner_id": 1,
  "base_entry_id": null,
  "owner": {
      "full_name": "Benjamin Rhodes", 
      "id": 1
  }, 
  "part_of_recurring_series": false, 
  "rrule": null,
  "rdate": null,
  "exrule": null,
  "exdate": null,
  "recurrence_end": null, 
  "start_time": null, 
  "type": "CalendarTask", 
  "updated_at": "2011/10/14 12:30:19 -0400"
  "all_day": true, 
  "association_id": 2, 
  "association_type": "Deal", 
  "category": {
      "id": 2, 
      "name": "Call"
  }, 
  "category_id": 2,
  "company_id": null, 
  "complete": true, 
  "completed_at": "2011/10/12 10:03:59 -0400", 
  "created_at": "2011/10/12 10:03:59 -0400", 
  "description": null, 
  "due_date": "2011/10/13", 
  "end_time": null, 
  "google_calendar_id": null, 
  "id": 1, 
  "name": "Introductory Call", 
  "owner_id": 1,
  "base_entry_id": null,
  "owner": {
      "full_name": "Benjamin Rhodes", 
      "id": 1
  }, 
  "part_of_recurring_series": false, 
  "rrule": null,
  "rdate": null,
  "exrule": null,
  "exdate": null,
  "recurrence_end": null, 
  "start_time": null, 
  "type": "CalendarTask", 
  "updated_at": "2011/10/14 12:30:19 -0400"
}

Delete a calendar entry

Request format

DELETE /calendar_entries/:id.json

The action returns an array of calendar entry ids that have been deleted. This array will always contain the base calendar entry id and any recurring entry ids if the entry was recurring.

Examples

curl -f -w "%{http_code}\n" -X DELETE \
  "https://api.pipelinedeals.com/api/v3/calendar_entries/10.json?api_key=abc1234"
HTTP Code
200
Body
empty

Failure Response

HTTP Code
404
Body
empty