Salesforce: Multi-Person Calendar Event (Contact / Lead as invitee)

In Salesforce, you can create event and relate to multiple Contacts (up to 50 contacts), but make sure you have enable Allow Users to Relate Multiple Contacts to Tasks and Events from Setup | Customize | Activities | Activity Settings.

You also can invite Contacts that is not defined in the Relate To for the event, including from Leads.

As you see from screenshot above, the event is relate to Opportunity and 2 contacts, we add both Contacts as invitee, and then we also add 2 Leads as Invitee.


So what happened in the backend ?

1. Event object
Salesforce create a new event record, because this is Multi-Person Calendar Event, notice GroupEventType = 1; while WhoId is the primary Contact.

Note that you cannot populate GroupEventType from API, but the value will be auto populate based on event category:

• 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.  

Sample query: Select Id, CreatedDate, ActivityDate, ActivityDateTime, ReminderDateTime, StartDateTime, EndDateTime, EventSubtype, GroupEventType, IsReminderSet, OwnerId, Subject, Type, WhatCount, WhatId, WhoCount, WhoId FROM Event WHERE Id = '00U63000001T8XGEA0'


2. EventRelation object
Represents people (a user, a lead, or contacts) or a resource (such as a conference room) invited to an event.  For above screenshot scenario, query to this object for above event will return 5 records: 2 Contacts, 2 Leads and 1 Opportunity.

Sample query: SELECT Id, EventId, RelationId, IsParent, IsWhat, IsInvitee, Status, CreatedDate FROM EventRelation WHERE EventId = '00U63000001T8XGEA0'

3. EventWhoRelation object
Represents the relationship between an event and a lead or contacts, this object DO NOT have relation with invitee, but it is pure on contacts or lead Relate To the Event. EventWhoRelation allows a variable number of relationships: one lead or up to 50 contacts. Available only if you’ve enabled Shared Activities for your organization.

Sample query: SELECT Id, EventId, RelationId, Type, CreatedDate FROM EventWhoRelation WHERE EventId = '00U63000001T8XGEA0'

From the top screenshot scenario, query will return 2 records which is Contact relate to: Mike Lee and Jack Man. We cannot create record directly in EventWhoRelation object with API.


How to auto add Contact / Lead as Invitee Event with API?

You just need to insert record(s) to EventRelation object, 1 record for 1 contact / lead. Here are fields you need to populate:
1. EventId = Event Id
2. RelationId = Contact Id / Lead Id
3. IsParent = False
4. IsWhat    = False
5. IsInvitee = True
6. Status         = New


Reference:

• Event
• EventRelation
• EventWhoRelation