# Calendar Sync API Requirements

BrightSync will interact with the following endpoints on your CRM connector to create, retrieve, and update calendar event objects.

### Calendar Event Object

BrightSync requires a CRM object (e.g., a Meeting or Calendar Event object) that can store the following or similar fields to facilitate two-way synchronization. 

| API Field        | Data Type       | Description                                                                              |
| ---------------- | --------------- | ---------------------------------------------------------------------------------------- |
| `id`             | String          | The unique identifier for the event in your CRM. Required for two-way sync.              |
| `subject`        | String          | The title of the calendar event.                                                         |
| `description`    | String          | The description or agenda of the meeting.                                                |
| `startTime`      | DateTime        | The start date and time of the event.                                                    |
| `endTime`        | DateTime        | The end date and time of the event.                                                      |
| `location`       | String          | The physical or virtual meeting location.                                                |
| `allDay`         | boolean         | Flag indicating if the event spans the entire day.                                       |
| `private`        | boolean         | Flag indicating if the event details should be hidden.                                   |
| `attendees`      | List\<Attendee> | A list of meeting participants (see structure below).                                    |
| `parentId`       | Long            | The ID of the parent meeting, for calendars that create child events for each attendee.  |
| `relatedTo`      | RealtedTo       | The CRM object(s) (Contact, Account, Opportunity) this meeting is linked/logged against. |
| `lastModifiedAt` | DateTime        | Timestamp of the last modification. Crucial for delta sync operations.                   |

#### Attendee Object Structure

The `Attendee` object within the event payload must support the following structure:

| API Field      | Data Type | Description                                                                  |
| -------------- | --------- | ---------------------------------------------------------------------------- |
| `userId`       | String    | The CRM user ID if the attendee is an internal system user.                  |
| `emailAddress` | String    | The email address of the attendee.                                           |
| `contactId`    | Long      | The ID of the associated Contact record in your CRM (if applicable).         |
| `status`       | String    | The RSVP status of the attendee (e.g., "Accepted," "Declined," "Tentative"). |

### Calendar Sync API Endpoints

Assuming one primary calendar. Additinal Calendar List API may be required if CRM supports multiple user calendars.

#### Read/Retrieve (Delta Sync) Endpoints

<table><thead><tr><th>Operation</th><th>Requirement</th><th width="82.7352294921875">Method</th><th>Endpoint Example</th></tr></thead><tbody><tr><td>Retrieve All in Interval</td><td>Endpoint to receive all events within a specified time range.</td><td><code>GET</code></td><td><code>/api/v1/events?startAt={timestamp}&#x26;endAt={timestamp}</code></td></tr><tr><td>Delta Sync (Modified/Changed)</td><td>Endpoint to retrieve events modified since a given timestamp (<code>lastModifiedAt</code>).</td><td><code>GET</code></td><td><code>/api/v1/events?since={timestamp}</code></td></tr><tr><td>Deleted Events Retrieval</td><td>Method to retrieve events that have been deleted (either via a <code>showDeleted=true</code> flag or a separate endpoint).</td><td><code>GET</code></td><td><code>/api/v1/deletedEvents?since={timestamp}</code></td></tr><tr><td>Load Event by ID</td><td>Standard endpoint to load a single event by its unique CRM ID.</td><td><code>GET</code></td><td><code>/api/v1/events/{id}</code></td></tr></tbody></table>

#### Write (CRUD) Endpoints

| Operation             | Requirement                                                           | Method           | Endpoint Example      |
| --------------------- | --------------------------------------------------------------------- | ---------------- | --------------------- |
| Create New Event      | Endpoint for creating a new calendar event in the CRM.                | `POST`           | `/api/v1/events`      |
| Update Existing Event | Endpoint for updating an existing calendar event based on its CRM ID. | `PATCH` or `PUT` | `/api/v1/events/{id}` |
| Delete Event          | Endpoint for deleting a calendar event based on its CRM ID.           |                  |                       |

#### &#x20;<br>