Cal.diy booking attendees and artifacts

Use these capabilities to manage the people attached to a booking or to read its generated calendar links, provider references, recording and transcript metadata, and conferencing sessions. This page owns the remaining 10 operations in the 22-operation booking family.

All operations use provider API version 2024-08-13. Every input and result in this group is restricted, contains PII, and requires redaction.

Choose an operation

Attendees and guests

Links, references, and meeting artifacts

Recording and transcript operations are reads, but their restricted-media boundary makes them high risk and approval-required.

List or read attendees

List accepts only a non-empty booking uid:

{
  "booking_uid": "booking-provider-uid"
}

Read one attendee by adding its integer provider id:

{
  "booking_uid": "booking-provider-uid",
  "attendee_id": 73
}

Additional fields are rejected. The connector percent-encodes booking_uid into the provider path. attendee_id is an integer without an additional minimum in the published schema; Cal.diy can still reject an id outside the provider’s domain.

These are low-risk, retry-safe reads. No capability-level human approval is required, but normal identity, tenant, account, and restricted-data policy still applies.

Add an attendee

Attendee add requires the booking uid, name, time zone, and email:

{
  "booking_uid": "booking-provider-uid",
  "name": "Avery Patel",
  "timeZone": "Europe/London",
  "email": "avery@example.com",
  "language": "en"
}

The locale enum is listed in the profile capability reference. Additional input fields are rejected.

Before the add request, the connector reads the booking. A passing preflight shows that the target was visible at that moment; it does not guarantee that the provider will accept the attendee.

The operation is medium risk and carries write, external_network, and send_message side effects. The connector description states that it updates connected calendar events. The marker does not prove that every participant received a notification or calendar update.

Remove an attendee

Attendee delete uses the same two-identifier input as attendee get:

{
  "booking_uid": "booking-provider-uid",
  "attendee_id": 73
}

The connector reads that exact attendee before deletion. The operation is high risk and destructive, and it can update connected calendar events or participant-visible state.

There is no rollback or compensating capability. Adding a person later creates a new provider change and does not restore prior invitation, attendance, or notification history.

Add guests

Guest add requires the guests field to contain 1 through 10 guest objects:

{
  "booking_uid": "booking-provider-uid",
  "guests": [
    {
      "email": "jordan@example.com",
      "name": "Jordan Lee",
      "timeZone": "America/New_York",
      "language": "en"
    }
  ]
}

Each guest requires only email. Optional fields are name, timeZone, phoneNumber, and language. The guest schema does not require non-empty name or timeZone; provider policy may impose stricter rules. Phone and language use the same constraints as attendee add. Additional guest fields are rejected.

The array does not declare uniqueItems, so duplicate guest objects can pass schema validation. Deduplicate intended recipients before approval rather than depending on provider behavior.

Guest add first reads the booking. It is medium risk and carries the send_message marker because the provider may send applicable notifications. It declares no compensation.

Read calendar links and references

Calendar-link get accepts only:

{
  "booking_uid": "booking-provider-uid"
}

It reads generated booking calendar links. The connector does not publish field names or expiry semantics for those provider-owned links.

Reference list requires the same booking uid and may add one type filter:

{
  "booking_uid": "booking-provider-uid",
  "type": "google_calendar"
}

The exact filter enum is:

google_calendar | office365_calendar | daily_video | google_video
office365_video | zoom_video

The filter is optional. These references identify provider calendar or video systems associated with the booking; they are not proof that an external event or meeting remains reachable.

Both operations are low-risk, retry-safe reads. Treat returned links and external identifiers as restricted even when a URL itself is shareable.

Read recordings and transcripts

Recording and transcript list each accept only the booking uid:

{
  "booking_uid": "booking-provider-uid"
}

These capabilities list restricted download metadata. They do not declare a media upload, streaming, or byte-download contract, and the connector does not publish the provider metadata field shape.

Both operations are high-risk reads and require approval because a response may expose restricted meeting media or transcript data. Approval uses the tenant-policy selector, a 900,000 ms validity window, and reason, input snapshot, and policy-decision evidence.

Approval must bind the actor, tenant, booking, capability, and exact input. A retry-safe marker does not bypass approval expiry, changed authorization, or a new booking uid.

Despite their high risk and approval requirement, both operations retain the read contract:

• optional action-scoped idempotency;
• connector retry support;
• retry safety safe;
• synchronous execution only.

Retry only within the current approval, deadline, and data-access policy. Do not automatically follow or download a URL found in provider metadata.

Read conferencing sessions

Conferencing-session list accepts only the booking uid and returns provider-owned session metadata:

{
  "booking_uid": "booking-provider-uid"
}

It is a low-risk, approval-free capability at the contract level. The result remains restricted and PII-bearing. Session presence does not prove that a meeting is active, joinable, recorded, or qualified for a particular provider.

Shared read contract

All seven reads are synchronous, retry-safe, and eligible for connector retry. Their idempotency key is optional, action-scoped, and collision-checked against the input hash.

Five reads are low risk and do not require capability-level approval. Recording and transcript list are the two high-risk exceptions described above. Risk and approval are independent contract fields; neither changes these operations into mutations.

Shared mutation contract

Attendee add, attendee delete, and guest add require:

All three mutations carry send_message. None declares a compensating capability. Attendee delete is destructive and uses the stricter destructive approval reason; add operations use the customer-visible-change reason.

An uncertain provider dispatch must be reconciled from the original durable operation. Do not issue the same people-changing action under a replacement key.

Result and redaction contract

The connector returns the validated provider JSON body as AIP output. A non-empty string status is required. data, pagination, and additional provider fields are optional; their shapes are not guaranteed by the connector schema.

The connector recursively replaces secret-, key-, and token-named values with [REDACTED]. This targeted redaction does not remove booking names, email addresses, phone numbers, URLs, transcripts, recording metadata, or other PII unless their field names match the secret redactor. Keep the full output under restricted-data controls.

Failures and recovery

Permanent provider rejection, invalid credentials, oversized responses, and durable settlement failures use the common Cal.diy error family. Gateway and lifecycle errors are described in the global error reference.

Verify attendee or artifact handling

For attendee changes, verify the approval and idempotency key, wait for a completed durable result, then list attendees or read the exact attendee. For guest add, read the booking and compare only the intended guest change.

For artifact reads, verify the exact capability, booking uid, actor, tenant, external account, approval when required, response status, and data-handling decision. Do not expose metadata merely because the operation completed.

Retain the provider request id when present. Reconcile uncertain mutations and never use a follow-up read as authorization to repeat a people-changing action.

These checks validate application handling. They do not prove notification delivery, media accessibility, live-provider qualification, or production readiness.

Related documentation

• Cal.diy capability index
• Core booking capabilities
• Authentication and tenant routing
• Transactions and compensation
• Error reference