Event

Represents an event in the calendar. In the user interface, event and task records are collectively referred to as activities.
Note

Note

  • An EventRelation object can’t be related to a child event, and child events don’t include the invitee related list.
  • query(), delete(), and update() aren’t allowed with events related to more than one contact in API versions 25.0 and earlier.

Supported Calls

create(), delete(), describeLayout(), describeSObjects(), getDeleted(), getUpdated(), query(), retrieve(), search(), undelete(), update(), upsert()

Fields

Field Details
AcceptedEventInviteeIds
Type
JunctionIdList
Properties
Create, Update
Description
A string array of contact or lead IDs who accepted this event. This JunctionIdList is linked to the AcceptedEventRelation child relationship.
Warning

Warning

Adding a JunctionIdList field name to the fieldsToNull property deletes all related junction records. This action can’t be undone.

AccountId
Type
reference
Properties
Filter, Group, Nillable, Sort
Description
Represents the ID of the related Account. The AccountId is determined as follows.

If the value of WhatId is any of the following objects, then Salesforce uses that object’s AccountId.

  • Account
  • Opportunity
  • Contract
  • Custom object that is a child of Account

If the value of the WhatId field is any other object, and the value of the WhoId field is a Contact object, then Salesforce uses that contact’s AccountId. (If your organization uses Shared Activities, Salesforce uses the AccountId of the primary contact.)

Otherwise, Salesforce sets the value of the AccountId field to null.

For information on IDs, see ID Field Type.

ActivityDate
Type
date
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Contains the event’s due date if the IsAllDayEvent flag is set to true. This field is a date field with a timestamp that is always set to midnight in the Coordinated Universal Time (UTC) time zone. Don’t attempt to alter the timestamp to account for time zone differences. Label is Due Date Only.

This field is required in versions 12.0 and earlier if the IsAllDayEvent flag is set to true.

The value for this field and StartDateTime must match, or one of them must be null.

ActivityDateTime
Type
dateTime
Properties
Create, Filter, Nillable, Sort, Update
Description
Contains the event’s due date if the IsAllDayEvent flag is set to false. This field is a regular Date/Time field with a relevant time portion. The time portion is always transferred in the Coordinated Universal Time (UTC) time zone. Translate the time portion to or from a local time zone for the user or the application, as appropriate. Label is Due Date Time.

This field is required in versions 12.0 and earlier if the IsAllDayEvent flag is set to false.

The value for this field and StartDateTime must match, or one of them must be null.

ClientGuid
Type
string
Properties
Filter, Group, Nillable, Sort
Description
The client globally unique identifier identifies the external API client used to create the event. Label is Client GUID.
CurrencyIsoCode
Type
picklist
Properties
Create, Defaulted on create, Filter, Group, Nillable, Restricted picklist, Sort, Update
Description
Available only for organizations with the multicurrency feature enabled. Contains the ISO code for any currency allowed by the organization.
DeclinedEventInviteeIds
Type
JunctionIdList
Properties
Create, Update
Description
A string array of contact, lead, or user IDs who declined this event. This JunctionIdList is linked to the DeclinedEventRelation child relationship.
Warning

Warning

Adding a JunctionIdList field name to the fieldsToNull property deletes all related junction records. This action can’t be undone.

Description
Type
textarea
Properties
Create, Nillable, Update
Description
Contains a text description of the event. Limit: 32,000 characters.
Division
Type
picklist
Properties
Defaulted on create, Filter, Group, Restricted picklist, Sort
Description
A logical segment of your organization's data. For example, if your company is organized into different business units, you could create a division for each business unit, such as “North America,” “Healthcare,” or “Consulting.” Available only if the organization has the Division permission enabled.
DurationInMinutes
Type
int
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Contains the event length, in minutes. Even though this field represents a temporal value, it is an integer type—not a Date/Time type.

Required in versions 12.0 and earlier if IsAllDayEvent is false.

In versions 13.0 and later, this field is optional, depending on the following:
  • If IsAllDayEvent is true, you can supply a value for either DurationInMinutes or EndDateTime. Supplying values in both fields is allowed if the values add up to the same amount of time. If both fields are null, the duration defaults to one day.
  • If IsAllDayEvent is false, a value must be supplied for either DurationInMinutes or EndDateTime. Supplying values in both fields is allowed if the values add up to the same amount of time.

If the multiday event feature is enabled, then API versions 13.0 and later support values greater than 1440 for the DurationInMinutes field. API versions 12.0 and earlier can’t access event objects whose DurationInMinutes is greater than 1440. For more information, see Multiday Events.

Depending on your API version, errors with the DurationInMinutes and EndDateTime fields may appear in different places.
  • Versions 38.0 and before—Errors always appear in the DurationInMinutes field.
  • Versions 39.0 and later—If there’s no value for the DurationInMinutes field, errors appear in the EndDateTime field. Otherwise, they appear in the DurationInMinutes field.
EndDateTime
Type
dateTime
Properties
Create, Filter, Nillable, Sort, Update
Description
Available in versions 13.0 and later. This field is a regular Date/Time field with a relevant time portion. The time portion is always transferred in the Coordinated Universal Time (UTC) time zone. Translate the time portion to or from a local time zone for the user or the application, as appropriate.

This field is optional, depending on the following:

  • If IsAllDayEvent is true, you can supply a value for either DurationInMinutes or EndDateTime. Supplying values in both fields is allowed if the values add up to the same amount of time. If both fields are null, the duration defaults to one day.
  • If IsAllDayEvent is false, a value must be supplied for either DurationInMinutes or EndDateTime. Supplying values in both fields is allowed if the values add up to the same amount of time.
Depending on your API version, errors with the DurationInMinutes and EndDateTime fields may appear in different places.
  • Versions 38.0 and before—Errors always appear in the DurationInMinutes field.
  • Versions 39.0 and later—If there’s no value for the DurationInMinutes field, errors appear in the EndDateTime field. Otherwise, they appear in the DurationInMinutes field.
EventSubtype
Type
picklist
Properties
Create, Filter, Group, Nillable, Restricted picklist, Sort
Description
Provides standard subtypes to facilitate creating and searching for events. This field isn’t updateable.
EventWhoIds
Type
JunctionIdList
Properties
Create, Update
Description
A string array of contact or lead IDs used to create many-to-many relationships with a shared event. EventWhoIds is available when the shared activities setting is enabled. The first contact or lead ID in the list becomes the primary WhoId if you don’t specify a primary WhoId. If you set the EventWhoIds field to null, all entries in the list are deleted and the value of WhoId is added as the first entry.
Warning

Warning

Adding a JunctionIdList field name to the fieldsToNull property deletes all related junction records. This action can’t be undone.

GroupEventType
Type
picklist
Properties
Defaulted on create, Filter, Group, Nillable, Restricted picklist, Sort
Description
Read-only. Available in API versions 19.0 and later.
The possible values are:
  • 0 (Non–group event)—An event with no invitees.
  • 1 (Group event)—An event with invitees.
  • 2 (Proposed event)—An event created when a user requests a meeting with a contact, lead, or person account using the Salesforce user interface. When the user confirms the meeting, the proposed event becomes a group event. You can’t create, edit, or delete proposed events in the API. This value is no longer used in API version 41.0 and later.
IsAllDayEvent
Type
boolean
Properties
Create, Defaulted on create, Filter, Group, Sort, Update
Description
Indicates whether the ActivityDate field (true) or the ActivityDateTime field (false) is used to define the date or time of the event. Label is All-Day Event. See also DurationInMinutes and EndDateTime.
IsArchived
Type
boolean
Properties
Defaulted on create, Filter, Group, Sort
Description
Indicates whether the event has been archived.
IsChild
Type
boolean
Properties
Defaulted on create, Filter, Group, Sort
Description
Indicates whether the event is a child of another event (true) or not (false).
For a child event, you can update IsReminderSet and ReminderDateTime only. You can query and delete a child event. If the objects related to the child event are different from those related to the parent event (this difference is possible if you use API version 25.0 or earlier) and one of the objects related to the child event is deleted, the objects related to the parent event are updated to ensure data integrity.
IsClientManaged
Type
boolean
Properties
Defaulted on create, Filter, Group, Sort
Description
Indicates whether the event is managed by an external client. If the value of this field is false, the event isn’t owned or managed by an external client, and Salesforce can be used to update it. If the value is true, Salesforce can be used to change only noncritical fields on the event. Label is Is Client Managed.
IsGroupEvent
Type
boolean
Properties
Defaulted on create, Filter, Group, Sort
Description
Indicates whether the event is a group event—that is, whether it has invitees (true) or not (false).
IsPrivate
Type
boolean
Properties
Create, Defaulted on create, Filter, Group, Sort, Update
Description
Indicates whether users other than the creator of the event can (false) or can’t (true) see the event details when viewing the event user’s calendar. However, users with the View All Data or Modify All Data permission can see private events in reports and searches, or when viewing other users’ calendars. Private events can’t be associated with opportunities, accounts, cases, campaigns, contracts, leads, or contacts. Label is Private.
IsRecurrence
Type
boolean
Properties
Create, Defaulted on create, Filter, Group, Sort
Description
Indicates whether the event is scheduled to repeat itself (true) or only occurs once (false). This is a read-only field when updating records, but not when creating them. If this field value is true, then RecurrenceEndDateOnly, RecurrenceStartDateTime, RecurrenceType, and any recurrence fields associated with the given recurrence type must be populated. Label is Create recurring series of events.
IsReminderSet
Type
boolean
Properties
Create, Defaulted on create, Filter, Group, Sort, Update
Description
Indicates whether the activity is a reminder (true) or not (false).
IsVisibleInSelfService
Type
boolean
Properties
Defaulted on create, Filter, Group, Sort
Description
Indicates whether an event associated with an object can be viewed in the Customer Portal (true) or not (false).

If your organization has enabled Communities, events marked IsVisibleInSelfService are visible to any external user in the community, as long as the user has access to the record the event was created on.

This field is available when Customer Portal or partner portal are enabled OR Communities is enabled and you have Customer Portal or partner portal licenses.

Location
Type
string
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Contains the location of the event.
OwnerId
Type
reference
Properties
Create, Defaulted on create, Filter, Group, Sort, Update
Description
Contains the ID of the user who owns the event. Label is Assigned to ID.
RecurrenceActivityId
Type
reference
Properties
Filter, Group, Nillable, Sort
Description
Read-only. Not required on create. Contains the ID of the main record of the recurring event. Subsequent occurrences have the same value in this field.
RecurrenceDayOfMonth
Type
int
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Indicates the day of the month on which the event repeats.
RecurrenceDayOfWeekMask
Type
int
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Indicates the day or days of the week on which the event repeats. This field contains a bitmask. The values are as follows:
  • Sunday = 1
  • Monday = 2
  • Tuesday = 4
  • Wednesday = 8
  • Thursday = 16
  • Friday = 32
  • Saturday = 64
Multiple days are represented as the sum of their numerical values. For example, Tuesday and Thursday = 4 + 16 = 20.
RecurrenceEndDateOnly
Type
date
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Indicates the last date on which the event repeats. For multiday recurring events, this is the day on which the last occurrence starts. This field is a date field with a timestamp that is always set to midnight in the Coordinated Universal Time (UTC) time zone. Don’t attempt to alter the timestamp to account for time zone differences.
RecurrenceInstance
Type
picklist
Properties
Create, Filter, Group, Nillable, Restricted picklist, Sort, Update
Description
Indicates the frequency of the event’s recurrence. For example, 2nd or 3rd.
RecurrenceInterval
Type
int
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Indicates the interval between recurring events.
RecurrenceMonthOfYear
Type
picklist
Properties
Create, Filter, Group, Nillable, Restricted picklist, Sort, Update
Description
Indicates the month in which the event repeats.
RecurrenceStartDateTime
Type
dateTime
Properties
Create, Filter, Nillable, Sort, Update
Description
Indicates the date and time when the recurring event begins. The value must precede the RecurrenceEndDateOnly. This field is a regular Date/Time field with a relevant time portion. The time portion is always transferred in the Coordinated Universal Time (UTC) time zone. Translate the time portion to or from a local time zone for the user or the application, as appropriate.
RecurrenceTimeZoneSidKey
Type
picklist
Properties
Create, Filter, Group, Nillable, Restricted picklist, Sort, Update
Description
Indicates the time zone associated with a recurring event. For example, “UTC-8:00” for Pacific Standard Time.
RecurrenceType
Type
picklist
Properties
Create, Filter, Group, Nillable, Restricted picklist, Sort, Update
Description
Indicates how often the event repeats. For example, daily, weekly, or every nth month (where “nth” is defined in RecurrenceInstance).
ReminderDateTime
Type
dateTime
Properties
Create, Filter, Nillable, Sort, Update
Description
Represents the time when the reminder is scheduled to fire, if IsReminderSet is set to true. If IsReminderSet is set to false, then the user may have deselected the reminder checkbox in the Salesforce user interface, or the reminder has already fired at the time indicated by the value.
ShowAs
Type
picklist
Properties
Create, Defaulted on create, Filter, Group, Nillable, Restricted picklist, Sort, Update
Description
Indicates how this event appears when another user views the calendar: Busy, Out of Office, or Free. Label is Show Time As.
StartDateTime
Type
dateTime
Properties
Create, Filter, Nillable, Sort, Update
Description
Indicates the start date and time of the event. Available in versions 13.0 and later.

If the Event IsAllDayEvent flag is set to true (indicating that it is an all-day Event), then the event start date information is contained in the StartDateTime field. This field is a regular Date/Time field with a relevant time portion. The time portion is always transferred in the Coordinated Universal Time (UTC) time zone. Translate the time portion to or from a local time zone for the user or the application, as appropriate.

If the Event IsAllDayEvent flag is set to false (indicating that it is not an all-day event), then the event start date information is contained in the StartDateTime field. The time portion is always transferred in the Coordinated Universal Time (UTC) time zone. You need to translate the time portion to or from a local time zone for the user or the application, as appropriate.

If this field has a value, then ActivityDate and ActivityDateTime must either be null or match the value of this field.

Subject
Type
combobox
Properties
Create, Filter, Nillable, Sort, Update
Description
The subject line of the event, such as Call, Email, or Meeting. Limit: 255 characters.
Type
Type
picklist
Properties
Create, Filter, Nillable, Update
Description
Indicates the event type, such as Call, Email, or Meeting.
UndecidedEventInviteeIds
Type
JunctionIdList
Properties
Create, Update
Description
A string array of contact, lead, or user IDs who are undecided about this event. This JunctionIdList is linked to the UndecidedEventRelation child relationship.
Warning

Warning

Adding a JunctionIdList field name to the fieldsToNull property deletes all related junction records. This action can’t be undone.

WhatCount
Type
int
Properties
Filter, Group, Nillable, Sort
Description
Available if your organization has enabled Shared Activities. Represents the count of related EventRelations pertaining to the WhatId. The count of the WhatId must be 1 or less.
WhatId
Type
reference
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The WhatId represents nonhuman objects such as accounts, opportunities, campaigns, cases, or custom objects. WhatIds are polymorphic. Polymorphic means a WhatId is equivalent to the ID of a related object. The label is Related To ID.
WhoCount
Type
int
Properties
Filter, Group, Nillable, Sort
Description
Available to organizations that have Shared Activities enabled. Represents the count of related EventRelations pertaining to the WhoId.
WhoId
Type
reference
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The WhoId represents a human such as a lead or a contact. WhoIds are polymorphic. Polymorphic means a WhoId is equivalent to a contact’s ID or a lead’s ID. The label is Name ID.

If Shared Activities is enabled, the value of this field is the ID of the related lead or primary contact. If you add, update, or remove the WhoId field, you might encounter problems with triggers, workflows, and data validation rules that are associated with the record. The label is Name ID.

If the JunctionIdList field is used, all WhoIds are included in the relationship list.

Beginning in API version 37.0, if the contact or lead ID in the WhoId field is not in the EventWhoIds list, no error occurs and the ID is added to the EventWhoIds as the primary WhoId. If WhoId is set to null, an arbitrary ID from the existing EventWhoIds list is promoted to the primary position.

Usage

Use Event to manage calendar appointments.

Querying and Filtering Events

Queries on events will be denied before they time out if they involve amounts of data that are deemed too large. In such cases, the exception code OPERATION_TOO_LARGE is returned. If you receive OPERATION_TOO_LARGE, refactor your query to return or scan a smaller amount of data.

When querying for events with a specific due date, you must filter on both the ActivityDateTime and ActivityDate fields. For example to find all events with a due date of February 14, 2003, you need two filters:
  • One filter with the ActivityDate field equal to the Coordinated Universal Time (UTC) time zone on February 14, 2003.
  • One filter with the ActivityDateTime field greater than or equal to midnight on February 14, 2003 in the user’s local time zone AND less than or equal to midnight on February 15, 2003 in the user’s local time zone.

Alternatively, in version 13.0 and later, you can find events with a specific due date by filtering on StartDateTime. For example, to find all events with a due date of February 14, 2003, filter with the StartDateTime greater than or equal to midnight on February 14, 2003 in the user's local time zone AND less than or equal to midnight on February 15, 2003 in the user's local time zone.

The EventId field of an EventRelation object always points to the master record. An invitee on a group event can query the EventRelation object to view the master record.

Multiday Events
  • Multiday events are available in version 13.0 and later. Also, in earlier versions SOQL queries do not return multiday events.
  • Multiday events are enabled through the user interface from Setup by entering Activity Settings in the Quick Find box, then selecting Activity Settings.
  • If the multiday event feature is enabled, then API versions 13.0 and later support values greater than 1440 for the DurationInMinutes field. API versions 12.0 and earlier can’t access event objects whose DurationInMinutes is greater than 1440.
  • Multiday events can’t exceed 14 days.

Recurring Events

  • Recurring events are available in version 7.0 and later.
  • After an event is created, it can’t be changed from recurring to nonrecurring or vice versa.
  • When you delete a recurring event series through the API, all past and future events in the series are removed. However, when you delete a recurring event series through the user interface, only future occurrences are removed.
  • When creating a recurring event series, the duration of the event must be 24 hours or less (either the DurationInMinutes or the difference between RecurrenceStartDateTime and EndDateTime must be greater than 24 hours). Once the recurring event series is created, you can extend the length of individual occurrences beyond 24 hours if Multiday events are enabled; see Multiday Events.
  • If IsRecurrence is true, then RecurrenceStartDateTime, RecurrenceEndDateOnly, RecurrenceType, and any properties associated with the given recurrence type (see the following table) must be populated.
  • When updating a recurring event series, it’s not possible to update the EventRelation for the event series object and the EventRelation for the series object occurrences at the same time.

The following table describes the usage of recurrence fields. Each recurrence type must have all of its properties set. All unused properties must be set to null.

RecurrenceType Value Properties Example Pattern
RecursDaily RecurrenceInterval Every second day
RecursEveryWeekday RecurrenceDayOfWeekMask Every weekday - can’t be Saturday or Sunday
RecursMonthly RecurrenceDayOfMonth RecurrenceInterval Every second month, on the third day of the month
RecursMonthlyNth RecurrenceInterval RecurrenceInstance RecurrenceDayOfWeekMask Every second month, on the last Friday of the month
RecursWeekly RecurrenceInterval RecurrenceDayOfWeekMask Every three weeks on Wednesday and Friday
RecursYearly RecurrenceDayOfMonth RecurrenceMonthOfYear Every March on the twenty-sixth day of the month
RecursYearlyNth RecurrenceDayOfWeekMask RecurrenceInstanceRecurrenceMonthOfYear The first Saturday in every October
JunctionIdList
To create an event using JuncionIdList, IDs are pulled from the related contacts and both the event and the EventRelation records are created in one API call. If the EventRelation fails, the event is rolled back because it’s all done in a single API call.
public void createEventNew(Contact[] contacts) {
	String[] contactIds = new String[contacts.size()];
	for (int i = 0; i < contacts.size(); i++) {
		contactIds[i] = contacts[i].getID();
	}
	Event event = new Event();
	event.setSubject("New Event");
	event.setEventWhoIds(contactIds);
	SaveResult[] results = null;
	try {
		results = connection.create(new Event[] {
			task
		});
	} catch (ConnectionException ce) {
		ce.printStackTrace();
	}
}

See Also