Cal.com Orgs / Routing forms API

openapi: 3.2.0
info:
  title: Cal.com API v2 Orgs / Routing forms API
  description: ''
  version: 1.0.0
  contact: {}
servers: []
tags:
- name: Orgs / Routing forms
paths:
  /v2/organizations/{orgId}/routing-forms:
    get:
      description: 'Required membership role: `org admin`. PBAC permission: `routingForm.readOrgRoutingForms`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_ROUTING_FORM_READ` scope is required.'
      operationId: OrganizationsRoutingFormsController_getOrganizationRoutingForms
      parameters:
      - name: Authorization
        in: header
        description: value must be `Bearer <token>` where `<token>` is api key prefixed with cal_
        required: true
        schema:
          type: string
      - name: orgId
        required: true
        in: path
        schema:
          type: number
      - name: skip
        required: false
        in: query
        description: Number of responses to skip
        schema:
          type: number
      - name: take
        required: false
        in: query
        description: Number of responses to take
        schema:
          type: number
      - name: sortCreatedAt
        required: false
        in: query
        description: Sort by creation time
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: sortUpdatedAt
        required: false
        in: query
        description: Sort by update time
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: afterCreatedAt
        required: false
        in: query
        description: Filter by responses created after this date
        schema:
          format: date-time
          type: string
      - name: beforeCreatedAt
        required: false
        in: query
        description: Filter by responses created before this date
        schema:
          format: date-time
          type: string
      - name: afterUpdatedAt
        required: false
        in: query
        description: Filter by responses created after this date
        schema:
          format: date-time
          type: string
      - name: beforeUpdatedAt
        required: false
        in: query
        description: Filter by responses updated before this date
        schema:
          format: date-time
          type: string
      - name: routedToBookingUid
        required: false
        in: query
        description: Filter by responses routed to a specific booking
        schema:
          type: string
      - name: teamIds
        required: false
        in: query
        description: Filter by teamIds. Team ids must be separated by a comma.
        schema:
          minItems: 1
          example: ?teamIds=100,200
          type: array
          items:
            type: number
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRoutingFormsOutput'
      summary: Get organization routing forms
      tags:
      - Orgs / Routing forms
      x-mcp:
        name: get_org_routing_forms
        guidance: List routing forms for an organization. Supports filtering by team IDs, date ranges, routed booking UID, and sorting.
      x-oauth-scopes:
      - ORG_ROUTING_FORM_READ
      x-platform-plan: ESSENTIALS
  /v2/organizations/{orgId}/routing-forms/{routingFormId}/responses:
    get:
      description: 'Required membership role: `org admin`. PBAC permission: `routingForm.readResponsePii`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_ROUTING_FORM_READ` scope is required.'
      operationId: OrganizationsRoutingFormsResponsesController_getRoutingFormResponses
      parameters:
      - name: Authorization
        in: header
        description: value must be `Bearer <token>` where `<token>` is api key prefixed with cal_
        required: true
        schema:
          type: string
      - name: orgId
        required: true
        in: path
        schema:
          type: number
      - name: routingFormId
        required: true
        in: path
        schema:
          type: string
      - name: skip
        required: false
        in: query
        description: Number of responses to skip
        schema:
          type: number
      - name: take
        required: false
        in: query
        description: Number of responses to take
        schema:
          type: number
      - name: sortCreatedAt
        required: false
        in: query
        description: Sort by creation time
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: sortUpdatedAt
        required: false
        in: query
        description: Sort by update time
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: afterCreatedAt
        required: false
        in: query
        description: Filter by responses created after this date
        schema:
          format: date-time
          type: string
      - name: beforeCreatedAt
        required: false
        in: query
        description: Filter by responses created before this date
        schema:
          format: date-time
          type: string
      - name: afterUpdatedAt
        required: false
        in: query
        description: Filter by responses created after this date
        schema:
          format: date-time
          type: string
      - name: beforeUpdatedAt
        required: false
        in: query
        description: Filter by responses updated before this date
        schema:
          format: date-time
          type: string
      - name: routedToBookingUid
        required: false
        in: query
        description: Filter by responses routed to a specific booking
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRoutingFormResponsesOutput'
      summary: Get routing form responses
      tags:
      - Orgs / Routing forms
      x-mcp:
        name: get_org_routing_form_responses
        guidance: Get responses for a specific routing form. Supports filtering by date ranges, routed booking UID, and sorting.
      x-oauth-scopes:
      - ORG_ROUTING_FORM_READ
      x-platform-plan: ESSENTIALS
    post:
      description: 'Required membership role: `org admin`. PBAC permission: `routingForm.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_ROUTING_FORM_WRITE` scope is required.'
      operationId: OrganizationsRoutingFormsResponsesController_createRoutingFormResponse
      parameters:
      - name: Authorization
        in: header
        description: value must be `Bearer <token>` where `<token>` is api key prefixed with cal_
        required: true
        schema:
          type: string
      - name: orgId
        required: true
        in: path
        schema:
          type: number
      - name: routingFormId
        required: true
        in: path
        schema:
          type: string
      - name: start
        required: true
        in: query
        description: "\n      Time starting from which available slots should be checked.\n    \n      Must be in UTC timezone as ISO 8601 datestring.\n      \n      You can pass date without hours which defaults to start of day or specify hours:\n      2024-08-13 (will have hours 00:00:00 aka at very beginning of the date) or you can specify hours manually like 2024-08-13T09:00:00Z\n      "
        schema:
          example: '2033-09-05'
          type: string
      - name: end
        required: true
        in: query
        description: "\n      Time until which available slots should be checked.\n      \n      Must be in UTC timezone as ISO 8601 datestring.\n      \n      You can pass date without hours which defaults to end of day or specify hours:\n      2024-08-20 (will have hours 23:59:59 aka at the very end of the date) or you can specify hours manually like 2024-08-20T18:00:00Z"
        schema:
          example: '2033-09-06'
          type: string
      - name: timeZone
        required: false
        in: query
        description: Time zone in which the available slots should be returned. Defaults to UTC.
        schema:
          example: Europe/Rome
          type: string
      - name: duration
        required: false
        in: query
        description: If event type has multiple possible durations then you can specify the desired duration here. Also, if you are fetching slots for a dynamic event then you can specify the duration her which defaults to 30, meaning that returned slots will be each 30 minutes long.
        schema:
          example: '60'
          type: number
      - name: format
        required: false
        in: query
        description: Format of slot times in response. Use 'range' to get start and end times.
        schema:
          example: range
          type: string
          enum:
          - range
          - time
      - name: bookingUidToReschedule
        required: false
        in: query
        description: The unique identifier of the booking being rescheduled. When provided will ensure that the original booking time appears within the returned available slots when rescheduling.
        schema:
          example: abc123def456
          type: string
      - name: rescheduleWithSameHost
        required: false
        in: query
        description: Only for round robin event types that allow the person rescheduling to choose the host. True returns slots of the original host, false returns slots of any available host. Ignored for other event types.
        schema:
          example: true
          type: boolean
      - name: queueResponse
        required: false
        in: query
        description: Whether to queue the form response.
        schema:
          example: true
          type: boolean
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateRoutingFormResponseOutput'
      summary: Create routing form response and get available slots
      tags:
      - Orgs / Routing forms
      x-oauth-scopes:
      - ORG_ROUTING_FORM_WRITE
      x-platform-plan: ESSENTIALS
  /v2/organizations/{orgId}/routing-forms/{routingFormId}/responses/{responseId}:
    patch:
      description: 'Required membership role: `org admin`. PBAC permission: `routingForm.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the `ORG_ROUTING_FORM_WRITE` scope is required.'
      operationId: OrganizationsRoutingFormsResponsesController_updateRoutingFormResponse
      parameters:
      - name: Authorization
        in: header
        description: value must be `Bearer <token>` where `<token>` is api key prefixed with cal_
        required: true
        schema:
          type: string
      - name: orgId
        required: true
        in: path
        schema:
          type: number
      - name: routingFormId
        required: true
        in: path
        schema:
          type: string
      - name: responseId
        required: true
        in: path
        schema:
          type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRoutingFormResponseInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateRoutingFormResponseOutput'
      summary: Update routing form response
      tags:
      - Orgs / Routing forms
      x-oauth-scopes:
      - ORG_ROUTING_FORM_WRITE
      x-platform-plan: ESSENTIALS
components:
  schemas:
    Routing:
      type: object
      properties:
        queuedResponseId:
          type:
          - string
          - 'null'
          description: The ID of the queued form response. Only present if the form response was queued.
          example: '123'
        responseId:
          type:
          - number
          - 'null'
          description: The ID of the routing form response.
          example: 123
        teamMemberIds:
          description: Array of team member IDs that were routed to handle this booking.
          example:
          - 101
          - 102
          type: array
          items:
            type: number
        teamMemberEmail:
          type: string
          description: The email of the team member assigned to handle this booking.
          example: john.doe@example.com
        skipContactOwner:
          type: boolean
          description: Whether to skip contact owner assignment from CRM integration.
          example: true
        crmAppSlug:
          type: string
          description: The CRM application slug for integration.
          example: salesforce
        crmOwnerRecordType:
          type: string
          description: The CRM owner record type for contact assignment.
          example: Account
        crmRecordOwnerFallbackTeamMemberIds:
          description: Eligible CRM owner fallback team member IDs to pass to the booking API.
          example:
          - 103
          - 104
          type: array
          items:
            type: number
        crmRecordOwnerFallbackMode:
          enum:
          - relationship
          - attributeRules
          type: string
          description: The CRM owner fallback strategy used for this routing result.
          example: relationship
      required:
      - teamMemberIds
    CreateRoutingFormResponseOutput:
      type: object
      properties:
        status:
          type: string
          example: success
          enum:
          - success
          - error
        data:
          $ref: '#/components/schemas/CreateRoutingFormResponseOutputData'
      required:
      - status
      - data
    UpdateRoutingFormResponseOutput:
      type: object
      properties:
        status:
          enum:
          - success
          - error
          type: string
          example: success
        data:
          $ref: '#/components/schemas/RoutingFormResponseOutput'
      required:
      - status
      - data
    SlotsOutput_2024_09_04:
      type: object
      properties: {}
    RangeSlotsOutput_2024_09_04:
      type: object
      properties: {}
    GetRoutingFormsOutput:
      type: object
      properties:
        status:
          enum:
          - success
          - error
          type: string
          example: success
        data:
          type: array
          items:
            $ref: '#/components/schemas/RoutingFormOutput'
      required:
      - status
      - data
    UpdateRoutingFormResponseInput:
      type: object
      properties:
        response:
          type: object
          additionalProperties: true
          description: The updated response data
    GetRoutingFormResponsesOutput:
      type: object
      properties:
        status:
          enum:
          - success
          - error
          type: string
          example: success
        data:
          type: array
          items:
            $ref: '#/components/schemas/RoutingFormResponseOutput'
      required:
      - status
      - data
    RoutingFormOutput:
      type: object
      properties:
        name:
          type: string
          example: My Form
        description:
          type:
          - string
          - 'null'
          example: This is the description.
        position:
          type: number
          example: 0
        routes:
          type:
          - object
          - 'null'
          additionalProperties: true
          description: Routing form routes configuration
        createdAt:
          type: string
          example: '2024-03-28T10:00:00.000Z'
          format: date-time
        updatedAt:
          type: string
          example: '2024-03-28T10:00:00.000Z'
          format: date-time
        fields:
          type:
          - object
          - 'null'
          additionalProperties: true
          description: Routing form fields configuration
        userId:
          type: number
          example: 2313
        teamId:
          type:
          - number
          - 'null'
          example: 4214321
        disabled:
          type: boolean
          example: false
        settings:
          type:
          - object
          - 'null'
          additionalProperties: true
          description: Routing form settings
        id:
          type: string
      required:
      - name
      - description
      - position
      - createdAt
      - updatedAt
      - userId
      - teamId
      - disabled
      - id
    CreateRoutingFormResponseOutputData:
      type: object
      properties:
        eventTypeId:
          type: number
          description: The ID of the event type that was routed to.
          example: 123
        routing:
          description: The routing information that could be passed as is to the booking API.
          example:
            eventTypeId: 123
            routing:
              teamMemberIds:
              - 101
              - 102
              teamMemberEmail: john.doe@example.com
              skipContactOwner: true
              crmRecordOwnerFallbackTeamMemberIds:
              - 103
              - 104
              crmRecordOwnerFallbackMode: attributeRules
          allOf:
          - $ref: '#/components/schemas/Routing'
        routingCustomMessage:
          type: string
          description: A custom message to be displayed to the user in case of routing to a custom page.
          example: This is a custom message.
        routingExternalRedirectUrl:
          type: string
          description: The external redirect URL to be used in case of routing to a non cal.com event type URL.
          example: https://example.com/
        slots:
          additionalProperties: true
          oneOf:
          - title: Time Slots
            $ref: '#/components/schemas/SlotsOutput_2024_09_04'
          - title: Slot Ranges
            $ref: '#/components/schemas/RangeSlotsOutput_2024_09_04'
    RoutingFormResponseOutput:
      type: object
      properties:
        id:
          type: number
        formId:
          type: string
        formFillerId:
          type: string
        routedToBookingUid:
          type: string
        response:
          type: object
          additionalProperties: true
          example:
            f00b26df-f54b-4985-8d98-17c5482c6a24:
              label: participant
              value: mamut
        createdAt:
          format: date-time
          type: string
      required:
      - id
      - formId
      - formFillerId
      - routedToBookingUid
      - response
      - createdAt
x-provenance:
  method: harvested
  publisher: Cal.com
  source: https://cal.com/docs/api-reference/v2/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)