Maintaining Calendars synchronization

While initial calendar synchronization lets us know about the user's busy times, integration must keep this knowledge up to date. For this purpose, we expect you to post new events and event updates when something is changed (event rescheduled, list of attendees or their response status is changed, title or other fields updated, etc.). There's a minimal number of fields we require such as event id, icaluid, start and end dates, see Upsert a calendar event for the full list and endpoint documentation. Other fields are optional and you should decide if you need to provide them depending on the requirements you want to implement for end-users.

• When a new event on a user's calendar is an internal organizational meeting that should not be associated with a person record in the Salesloft app, payload can be limited to the event IDs that can be used to update an event later if it is rescheduled or canceled, and event start and end dates so that we can reserve a time slot on a calendar for meetings scheduled through Salesloft.
• When a new event on a user's calendar is a meeting with a prospect, and you want Salesloft to capture it for any of the following reasons: displaying the event on the meetings dashboard and person page, syncing it with the SFDC, tracking it in analytics, and so on, payload should contain additional information, such as attendees list, title, description, etc. It's important to keep an eye on the updates to recurring events; whenever a sequence of events is modified, each occurrence of the event must be updated via API.

The current state of a user's calendar can be verified via the List calendar events endpoint.

Important:

• The Bulk API is not designed for time-sensitive tasks and is intended to handle one job at a time. Please note that your team shares a bulk job queue, and using this endpoint for time-sensitive tasks may result in delays or errors for other team members who are also using this endpoint.
• If you need to quickly sync a small number of events, we recommend using the /v2/calendar/events/upsert endpoint. For each event, you must send a separate request to this endpoint.

Upserting events:

POST /v2/calendar/events/upsert

The upsert key is a combination of id and i_cal_uid scoped to the specified calendar_id. This endpoint can be used to update a single event. For processing large batches of events, please utilize the Bulk API.

Request:

• Headers:
  • Authorization: Bearer <api_key>
• Url Params: No specific query parameters needed.
• Body:

{
  "calendar_id": "external_00000000-0000-0000-0000-000000000000",
  "id": "nCwjFxlX",
  "i_cal_uid": "LUHIDq0to6tM@domain.example.com",
  "start_time": "2022-08-04T16:00:00-07:00",
  "end_time": "2022-08-04T16:30:00-07:00",
  "title": "Intro to the product capabilities",
  "attendees": [
      {
          "name": "Jim Haplert",
          "email": "jim.halpert@example.com",
          "status": "accepted",
          "organizer": true
      },
      {
          "name": "Gabe Lewis",
          "email": "gabe.lewis@example.com",
          "status": "needsAction",
          "organizer": false
      }
  ],
  // You can include an updated_at field for events to prevent overwriting newer data with outdated information. In Bulk API, where multiple jobs may have the same event, adding updated_at ensures our system skips updates with older values than those in our database.
  "updated_at": "2022-08-04T16:30:00-07:00"
}

• For Bulk API, same payload should be provided in the data array.

{
  "data": [
      {
          "id": "VuNfsnuW",
          "i_cal_uid": "pZH2vAzwYwg9@domain.example.com",
          "start_time": "2022-10-23T09:00:00.394Z",
          "end_time": "2022-10-23T09:30:00.394Z",
          "calendar_id": "external_00000000-0000-0000-0000-000000000000",
          ...
      },
      {
          "id": "iJc04yGg",
          "i_cal_uid": "Ay4YCdWWAEU3@domain.example.com",
          "start_time": "2022-10-23T13:15:00.033Z",
          "end_time": "2022-10-23T13:45:00.033Z",
          "calendar_id": "external_00000000-0000-0000-0000-000000000000"
      },
      ...
  ]
}

Response:

• Status: 201
• Body:

{
  "data": {
      "all_day": false,
      "attendees": [
          {
              "deleted_at": null,
              "name": "Jim Haplert",
              "email": "jim.halpert@example.com",
              "organizer": true,
              "status": "accepted",
              "status_changed": true
          },
          {
              "deleted_at": null,
              "name": "Gabe Lewis",
              "email": "gabe.lewis@example.com",
              "organizer": false,
              "status": "needsAction",
              "status_changed": false
          }
      ],
      "body_html": null,
      "busy": true,
      "calendar_id": "external_00000000-0000-0000-0000-000000000000",
      "canceled_at": null,
      "conference_data": {},
      "created_at": "2022-08-02T16:53:40",
      "creator": null,
      "description": "This field was not passed in the request and will remain unchanged",
      "end_time": "2022-08-04T23:30:00Z",
      "extended_properties": {
          "changed_attributes": [
              "attendees",
              "end_time",
              "start_time",
              "title"
          ]
      },
      "html_link": null,
      "i_cal_uid": "LUHIDq0to6tM@domain.example.com",
      "id": "nCwjFxlX",
      "location": null,
      "organizer": null,
      "provider": "external",
      "recurring": false,
      "start_time": "2022-08-04T23:00:00Z",
      "status": null,
      "tenant_id": 1,
      "title": "Intro to the product capabilities",
      "updated_at": "2022-10-21T11:44:43.216099Z",
      "user_guid": "00000000-0000-0000-0000-000000000000"
  },
  "upsert_type": "update"
}