> ## Documentation Index > Fetch the complete documentation index at: https://developer.zeeg.me/llms.txt > Use this file to discover all available pages before exploring further. # Handover a Scheduled Event > Reassign a scheduled Round Robin event from its current host to another eligible host in your workspace. ## OpenAPI ````yaml PUT /scheduled-events/{uuid}/handover openapi: 3.0.0 info: title: Zeeg Public API description: >- Zeeg public API documentation. ## Authentication All endpoints require a Bearer token. You can generate an API token from [your Zeeg dashboard](https://app.zeeg.me/account/settings/api-access). Each token is scoped to specific permissions (e.g. `events:read`, `webhooks:write`). Make sure your token has the required scopes for the endpoints you want to use. ## Recommended Headers We recommend including the `Accept: application/json` header in all API requests to ensure you receive JSON responses. version: 2.0.0 x-logo: url: https://app.zeeg.me/img/logo-dark.2ca83593.svg backgroundColor: '#f7f7f9' altText: zeeg contact: name: Zeeg Support email: support@zeeg.me url: https://zeeg.me/en/contact license: name: Proprietary url: https://zeeg.me/en/legal/terms termsOfService: https://zeeg.me/en/legal/terms servers: - url: https://api.zeeg.me/v2 description: Production security: - bearer: [] tags: - name: Scheduled Events description: Management of events scheduled via Zeeg - name: Scheduling Pages description: Scheduling pages information and management - name: Availability Schedule description: Read and change availability for users - name: Webhooks description: Webhooks management - name: Notes description: Notes for scheduled events - name: Workspaces & Teams description: Workspace users and team member management - name: AI Agent description: AI Agent integration endpoints - name: Payloads description: Webhook payload schemas - name: CRM - Objects description: >- Discover the schema of CRM objects (standard and custom) including all attribute definitions - name: CRM - Companies description: Create, read, update, and delete CRM company records - name: CRM - People description: Create, read, update, and delete CRM person records - name: Routing Forms - Forms description: Read routing forms with their questions and their routes - name: Routing Forms - Submissions description: Read and delete the submissions that invitees send through a routing form paths: /scheduled-events/{uuid}/handover: parameters: - schema: type: string format: uuid example: zg-O69bac566950c6 name: uuid in: path required: true description: UUID of a specific scheduled event (zg-XXX format) put: tags: - Scheduled Events summary: Handover a scheduled event description: >- This endpoint allows you to handover a scheduled event identified by its unique **UUID** to another host in the event type for Round Robin without changing the meeting links. - The new host must be a member of the event type hosts; however, you can let the system automatically pick an available host by not providing `newHostEmail` in the request. - Host availability can be ignored by setting `requireHostAvailability` to `false`; please note that this means the new host will get overlapping events. - For a booking outside the conditions below, set `fallbackToReschedule` to `true` to reschedule it to the new host at the same time instead. - A booking that moves in place emails the new host and the previous host, unless the event type turns host emails off. The invitee receives no email. A booking rescheduled through `fallbackToReschedule` sends the usual reschedule emails instead. #### Current limitation The booking moves in place only under the following conditions: - Supports only Round Robin events. - The event must be synchronized to either a Microsoft calendar OR no calendar. - The location must NOT be Zoom, Webex or Demodesk. Other locations are supported. operationId: put-api-scheduled-events-uuid-handover requestBody: description: '' content: application/json: schema: type: object properties: newHostEmail: type: string description: >- The email of the new host for the event. When not provided, the system will automatically select a new host if available. format: email example: marco.rossi@horizondigital.de requireHostAvailability: type: boolean description: >- Only hand the booking to a host who is free at the event time. When `false`, the new host receives the booking whether or not the slot is free. default: true fallbackToReschedule: type: boolean description: >- When the booking cannot move in place (it sits in a calendar other than Microsoft, or its location is Zoom, Webex or Demodesk), reschedule it to the new host at the same time instead of failing the call. It does not apply when the new host is busy: with `requireHostAvailability` set to `true`, that call fails either way. This path goes through a reschedule, so the booking gets a new event `uuid` and a new invitee `uuid`. Leave it `false` to keep the identifiers the caller already holds. default: false examples: Handing over to a specific host without requiring availability: value: newHostEmail: marco.rossi@horizondigital.de requireHostAvailability: false fallbackToReschedule: false responses: '200': description: OK content: application/json: schema: type: object properties: resource: $ref: '#/components/schemas/ScheduledEvent' examples: Successful event handover: value: resource: uri: >- https://api.zeeg.me/v2/scheduled-events/zg-O69bac566950c6 uuid: zg-O69bac566950c6 title: 30-Minute Discovery Call type: ROUND_ROBIN startTime: '2026-04-15T09:00:00.000000Z' endTime: '2026-04-15T09:30:00.000000Z' duration: 30 status: active eventTypeUri: >- https://api.zeeg.me/v2/event-types/80f46bf5-eb01-4c07-960e-a9a3e18aae5e location: null maxActiveInvitees: 1 activeInviteesCount: 1 invitees: - uuid: zg-O69bad4047abf0 salutation: Ms. fullName: Sophie Laurent email: sophie.laurent@northwind.io guests: [] timeZone: Europe/Paris cancellation: cancelledAt: null cancelledBy: null cancellerType: null cancellationReason: null payment: null noShow: false noShowAt: null scheduledAt: '2026-04-10T08:30:00.000000Z' utm: utm_campaign: spring_launch utm_source: linkedin utm_medium: social utm_content: null utm_term: null customQueryParams: {} guests: [] hosts: - firstName: Marco lastName: Rossi email: marco.rossi@horizondigital.de slug: marco-rossi url: https://zeeg.me/marco-rossi avatarUrl: null teamName: Sales createdAt: '2026-04-10T08:30:00.000000Z' updatedAt: '2026-04-15T10:05:00.000000Z' currentTime: '2026-04-15T10:05:00+00:00' '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean message: type: string status: type: integer examples: Not a Round Robin event: value: success: false message: Only round robin events can be reassigned to another host. status: 400 Host not found: value: success: false message: Host not found. status: 400 Same host selected: value: success: false message: The selected host is the same as the current event host. status: 400 '401': $ref: '#/components/responses/401' '500': description: Internal Server Error content: application/json: schema: type: object properties: success: type: boolean message: type: string status: type: integer examples: Event not found: value: success: false message: Event not found status: 500 security: - bearer: [] components: schemas: ScheduledEvent: type: object required: - uri - uuid - title - type - startTime - endTime - duration - status - eventTypeUri - maxActiveInvitees - activeInviteesCount - invitees - teamName - createdAt properties: uri: type: string format: uri description: Public API URI of the scheduled event resource. uuid: type: string description: Zeeg event identifier (zg-XXX format) example: zg-O69bac566950c6 title: type: string description: Title of the scheduled event. type: type: string description: Event type kind (e.g. `ONE_ON_ONE`, `GROUP`, `ROUND_ROBIN`). startTime: type: string format: date-time description: ISO 8601 UTC start time of the booked event. endTime: type: string format: date-time description: ISO 8601 UTC end time of the booked event. duration: type: integer description: Event duration in minutes. status: type: string description: Booking status (e.g. `confirmed`, `cancelled`). eventTypeUri: type: string format: uri description: Public API URI of the event type this booking was made against. location: type: object nullable: true required: - type properties: type: type: string description: >- Location type (e.g. `google_meet`, `zoom`, `phone`, `in_person`). joinUrl: type: string format: uri description: Join URL for the meeting, when applicable. nullable: true description: Meeting location for the booking. maxActiveInvitees: type: integer description: Maximum number of active invitees the event allows. activeInviteesCount: type: integer description: Current number of active (non-cancelled) invitees. invitees: type: array items: $ref: '#/components/schemas/ScheduledInvitee' description: Invitees booked on the scheduled event. guests: type: array description: >- Email addresses of additional guests added across all invitees. An empty array when none were added. items: type: string hosts: type: array nullable: true items: type: object required: - firstName - email - slug - url properties: firstName: type: string description: Host's first name. nullable: true lastName: type: string description: Host's last name. Empty string when not set. email: type: string format: email description: Host's email address. nullable: true slug: type: string description: Host's public profile slug. nullable: true url: type: string format: uri description: Host's public profile URL. avatarUrl: type: string format: uri nullable: true description: URL of the host's avatar image, if set. description: Hosts assigned to the scheduled event. teamName: type: string nullable: true description: >- Name of the team that owns the scheduling page the booking was made on, or `null` for a personal scheduling page. The key is always present. This is the same value the `invitee.scheduled` webhook sends as `teamName` for the same booking. example: Sales createdAt: type: string format: date-time description: ISO 8601 UTC timestamp when the booking was created. updatedAt: type: string format: date-time description: ISO 8601 UTC timestamp when the booking was last updated. currentTime: type: string format: date-time description: Current server time description: >- A scheduled event resource. This is the single canonical shape returned by all scheduled-event endpoints and embedded in the AI agent call webhook payload. ScheduledInvitee: type: object required: - fullName - email - timeZone - scheduledAt - noShow properties: uuid: type: string description: Zeeg attendee identifier (zg-XXX format) example: zg-O69bac566950c6 salutation: type: string nullable: true description: Salutation for the invitee, if collected. fullName: type: string description: Full name of the invitee. nullable: true email: type: string format: email description: Email address of the invitee. nullable: true guests: type: array description: >- Email addresses of additional guests the invitee added. An empty array when the invitee added none. items: type: string timeZone: type: string description: IANA time zone of the invitee. nullable: true cancellation: type: object properties: cancelledAt: type: string format: date-time nullable: true description: ISO 8601 UTC timestamp when the invitee was cancelled. cancelledBy: type: string nullable: true description: Identifier of who cancelled the booking. cancellerType: type: string nullable: true description: Type of canceller (e.g. host, invitee). cancellationReason: type: string nullable: true description: Reason given for the cancellation. description: >- Cancellation details. All fields are `null` when the invitee is not cancelled. payment: type: object nullable: true description: Payment details for the booking, or `null` when no payment applies. properties: gateway: type: string description: Payment provider, e.g. `stripe` or `paypal`. price: type: number currency: type: string transactionId: type: string nullable: true createdAt: type: string format: date-time status: type: string enum: - pending - success description: '`pending` until the transaction completes.' noShow: type: boolean description: Whether the invitee has been marked as a no-show. Always present. noShowAt: type: string format: date-time nullable: true description: >- ISO 8601 UTC timestamp when the invitee was marked as a no-show, or `null` when they were not. scheduledAt: type: string format: date-time description: ISO 8601 UTC timestamp when the invitee booked. nullable: true utm: type: object required: - utm_campaign - utm_source - utm_medium - utm_term - utm_content properties: utm_campaign: type: string nullable: true utm_source: type: string nullable: true utm_medium: type: string nullable: true utm_content: type: string nullable: true utm_term: type: string nullable: true description: >- UTM tracking parameters captured at booking time. Always holds these five keys, in `snake_case`; a key holds `null` when the booking did not carry a value for it. adAttribution: type: object nullable: true properties: gclid: type: string nullable: true description: Google Ads click ID. gbraid: type: string nullable: true description: >- Google click ID for iOS app-to-web clicks. Mutually exclusive with `gclid` per click. wbraid: type: string nullable: true description: >- Google click ID for web-to-app clicks. Mutually exclusive with `gclid` per click. fbclid: type: string nullable: true description: Meta click ID. fbp: type: string nullable: true description: Meta browser ID cookie (`_fbp`) captured at booking time. fbc: type: string nullable: true description: Meta click cookie (`_fbc`) captured at booking time. landingUrl: type: string nullable: true description: Full URL of the host page the booking widget was embedded on. description: >- Ad-click identifiers captured at booking time, keyed by provider. Only the keys that were actually captured are present; `null` when none were captured. customQueryParams: type: object description: >- Custom query parameters captured at booking time, keyed by the `c__`-prefixed parameter name. An empty object when the booking captured none. example: c__ref: nl-2026-04 questions: type: array nullable: true items: type: object properties: answer: type: string answer_type: type: string question: type: string description: Booking questions answered by the invitee. agentBookingReference: type: string nullable: true description: Reference code for bookings made via the AI agent; `null` otherwise. cancelUrl: type: string format: uri nullable: true description: >- Public URL the invitee uses to cancel this booking. `null` once the booking is cancelled. rescheduleUrl: type: string format: uri nullable: true description: >- Public URL the invitee uses to reschedule this booking. `null` once the booking is cancelled. rescheduled: type: boolean description: >- True once this booking has been superseded by a reschedule. A rescheduled booking reports `status: cancelled` for backward compatibility; `rescheduled` and `nextRescheduling` are how a caller tells a reschedule apart from an actual cancellation. rescheduling: allOf: - $ref: '#/components/schemas/EventRescheduling' nullable: true description: >- Present when this booking is the *result* of a reschedule. `null` when this booking was not itself created by rescheduling an earlier one. nextRescheduling: allOf: - $ref: '#/components/schemas/EventRescheduling' nullable: true description: >- Present when this booking has been superseded by a later reschedule. `null` when the booking has not been rescheduled. description: >- One invitee of a scheduled event. The scheduled event embeds it in `invitees`, and the invitee endpoints return it as `resource`. EventRescheduling: type: object description: >- Links one half of a reschedule to the other. Embedded as `rescheduling` (on the new booking) and `nextRescheduling` (on the superseded booking) inside an invitee. properties: oldStartAt: type: string format: date-time nullable: true description: >- ISO 8601 UTC start time the previous booking held before the reschedule. newStartAt: type: string format: date-time nullable: true description: ISO 8601 UTC start time the new booking was moved to. rescheduledAt: type: string format: date-time description: ISO 8601 UTC timestamp when the reschedule was performed. previousEventUuid: type: string nullable: true description: >- uuid of the superseded booking (zg-XXX format). Use it directly as the `uuid` path parameter of `GET /scheduled-events/{uuid}` to fetch that booking. example: zg-O69bad4047abf0 previousInviteeUuid: type: string nullable: true description: >- uuid of the invitee on the superseded booking. No public endpoint accepts an invitee uuid as a path parameter. example: zg-O69bac566950c6 reason: type: string nullable: true description: Reason given for the reschedule, if any. rescheduledBy: type: string nullable: true description: Who performed the reschedule (e.g. `host`, `invitee`). reschedulerFullName: type: string nullable: true description: Full name of the person who performed the reschedule, when known. responses: '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: Unauthenticated. examples: Unauthenticated: value: message: Unauthenticated. securitySchemes: bearer: type: http scheme: bearer description: '' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.