Skip to main content

Upsert Calendar Event

POST 
/calendar/event/upsert

Creates or updates a calendar event in a single call — no need to check whether the event already exists. This is the recommended endpoint for external integrations (e.g. Zapier, CRM sync) because it eliminates the if/else logic of calling add vs update.

Match priority (first match wins):

  1. eventId — exact Terros event ID match
  2. sourceId — external system ID, with owner → account → company fallback
  3. Location + owner — if a location resolves and an event exists at that location for the same owner

If no match is found, a new event is created. If a match is found, the provided fields are merged into the existing event (unset fields are left unchanged).

Tips:

  • Always include sourceId when syncing from an external system — it ensures idempotent writes and lets Terros track the external record ID.
  • For Comeback events, include previousEventId pointing to the original Consultation.
  • notes is deprecated — use Workflow account notes for new integrations.

Defaults on create (applied only when the field is omitted):

  • eventType → Consultation
  • ownerId → the authenticated user
  • duration → 60 minutes
  • eventDate → current time
  • title → Untitled Event From Integration

Update behavior (when a match is found):

  • Only provided fields are updated — omitted fields keep their existing values.
  • attendeeId supports explicit null to clear the field. All other fields treat null and undefined the same (preserve existing).

Outcome matching: outcomeId is flexible — it can be:

  1. A Terros EventOutcomeId (exact match)
  2. An integration mapping string configured on the outcome
  3. A case-insensitive outcome name

User resolution: ownerId, attendeeId, and dispatcherId each accept either a Terros UserId (e.g. U:abc123) or an email address. The system resolves emails to users within the authenticated company.

Request​

Responses​

Success