Sarj AI Developer API Zoho API

openapi: 3.2.0
info:
  title: Sarj.ai Voice Zoho API
  version: 1.0.0
tags:
- name: zoho
paths:
  /v1/beta/integrations/zoho/authorize:
    get:
      tags:
      - zoho
      summary: Zoho Authorize
      operationId: integrationsZohoAuthorize
      parameters:
      - name: return_to
        in: query
        required: true
        schema:
          type: string
          title: Return To
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZohoAuthorizeUrlResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/beta/integrations/zoho/webhook:
    post:
      tags:
      - zoho
      summary: Zoho Webhook
      description: Public webhook API where ZohoCRM dumps its webhook data.
      operationId: integrationsZohoWebhook
      parameters:
      - name: extra_conditions
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Extra Conditions
      - name: scenario_id
        in: query
        required: true
        schema:
          type: string
          title: Scenario Id
      - name: user_email
        in: query
        required: true
        schema:
          type: string
          title: User Email
      - name: user_id
        in: query
        required: true
        schema:
          type: string
          title: User Id
      - name: organization_id
        in: query
        required: true
        schema:
          type: string
          title: Organization Id
      - name: trunk_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Trunk Id
      - name: language
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/Language'
          default: ar
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ZohoNotificationWebhookPayload_dict_str__object__'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/beta/integrations/zoho/list-webhooks:
    get:
      tags:
      - zoho
      summary: Get Notifications
      operationId: integrationsGetNotifications
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZohoNotificationGetResponse'
  /v1/beta/integrations/zoho/create-webhook:
    post:
      tags:
      - zoho
      summary: Create Notification
      operationId: integrationsCreateNotification
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ZohoWebhookData'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZohoNotificationCreateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/beta/integrations/zoho/disable-webhooks:
    delete:
      tags:
      - zoho
      summary: Remove Notifications
      operationId: integrationsRemoveNotifications
      parameters:
      - name: channel_ids
        in: query
        required: true
        schema:
          type: string
          description: Comma-separated list of channel IDs
          title: Channel Ids
        description: Comma-separated list of channel IDs
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZohoNotificationDeleteResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/beta/integrations/zoho/available-events:
    get:
      tags:
      - zoho
      summary: Get Available Events
      description: "Return available Zoho CRM events that can be used for webhooks.\n\nReturns:\n    The\
        \ subscribable notification events grouped by CRM module."
      operationId: integrationsGetAvailableEvents
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZohoAvailableEventsResponse'
  /v1/beta/integrations/zoho/field-settings:
    get:
      tags:
      - zoho
      summary: Get Field Settings
      operationId: integrationsGetFieldSettings
      parameters:
      - name: crm_module
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ZohoCRMModules'
          default: Leads
      - name: editable_fields_only
        in: query
        required: false
        schema:
          type: boolean
          default: true
          title: Editable Fields Only
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ZohoFieldSetting'
                title: Response Integrationsgetfieldsettings
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/beta/integrations/zoho/record:
    get:
      tags:
      - zoho
      summary: Get Record
      description: "Read a CRM record back over HTTP so the canary can verify its lead update landed.\n\
        \nReturns:\n    The CRM record with its callable fields.\n\nRaises:\n    HTTPException: 404 if\
        \ no record exists with `record_id` in `module`."
      operationId: integrationsGetRecord
      parameters:
      - name: record_id
        in: query
        required: true
        schema:
          type: string
          title: Record Id
      - name: module
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ZohoCRMModules'
          default: Leads
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZohoCallableRecord'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/beta/integrations/zoho/revalidate-all-webhooks:
    post:
      tags:
      - zoho
      summary: Revalidate All Notifications
      description: Revalidate notifications for all organizations with Zoho tokens.
      operationId: integrationsRevalidateAllNotifications
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/beta/integrations/zoho/desk/create-ticket:
    post:
      tags:
      - zoho
      summary: Create Ticket
      description: "Create a ticket in Zoho Desk for the specified organization.\n\nReturns:\n    The\
        \ ticket as created in Zoho Desk."
      operationId: integrationsCreateTicket
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTicketRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeskTicketGet'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ZohoWebhookQueryParams:
      properties:
        scenario_id:
          type: string
          title: Scenario Id
        user_email:
          type: string
          title: User Email
        user_id:
          type: string
          title: User Id
        organization_id:
          type: string
          title: Organization Id
        trunk_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Trunk Id
        language:
          $ref: '#/components/schemas/Language'
          default: ar
      type: object
      required:
      - scenario_id
      - user_email
      - user_id
      - organization_id
      title: ZohoWebhookQueryParams
      description: The query params retrieved from Zoho webhooks
    _OperationType:
      properties:
        web_update:
          type: boolean
          title: Web Update
        api_create:
          type: boolean
          title: Api Create
        web_create:
          type: boolean
          title: Web Create
        api_update:
          type: boolean
          title: Api Update
      type: object
      required:
      - web_update
      - api_create
      - web_create
      - api_update
      title: _OperationType
    ZohoNotificationGetResponse:
      properties:
        watch:
          items:
            $ref: '#/components/schemas/_WatchResponse'
          type: array
          title: Watch
      type: object
      title: ZohoNotificationGetResponse
    ZohoAuthorizeUrlResponse:
      properties:
        authorize_url:
          type: string
          title: Authorize Url
      type: object
      required:
      - authorize_url
      title: ZohoAuthorizeUrlResponse
      description: Zoho consent-page URL for the browser to navigate to.
    _NotificationResponseCreate:
      properties:
        code:
          type: string
          const: SUCCESS
          title: Code
        details:
          $ref: '#/components/schemas/_NotificationDetails'
        message:
          type: string
          title: Message
      type: object
      required:
      - code
      - details
      - message
      title: _NotificationResponseCreate
    ZohoNotificationWebhookPayload_dict_str__object__:
      properties:
        server_time:
          type: integer
          title: Server Time
        affected_values:
          items:
            $ref: '#/components/schemas/Record_dict_str__object__'
          type: array
          title: Affected Values
        query_params:
          additionalProperties: true
          type: object
          title: Query Params
        module:
          $ref: '#/components/schemas/ZohoCRMModules'
        ids:
          items:
            type: string
          type: array
          title: Ids
        operation:
          type: string
          enum:
          - insert
          - update
          title: Operation
        channel_id:
          type: string
          title: Channel Id
        token:
          type: string
          title: Token
      type: object
      required:
      - server_time
      - affected_values
      - query_params
      - module
      - ids
      - operation
      - channel_id
      - token
      title: ZohoNotificationWebhookPayload[dict[str, object]]
    ZohoFieldSetting:
      properties:
        api_name:
          type: string
          title: Api Name
        display_label:
          type: string
          title: Display Label
        read_only:
          type: boolean
          title: Read Only
        operation_type:
          $ref: '#/components/schemas/_OperationType'
          description: Allowed operations on this field.
        json_type:
          type: string
          enum:
          - boolean
          - integer
          - double
          - string
          - jsonarray
          - jsonobject
          title: Json Type
        tooltip:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Tooltip
        pick_list_values:
          anyOf:
          - items:
              $ref: '#/components/schemas/ZohoPickListValue'
            type: array
          - type: 'null'
          title: Pick List Values
        length:
          anyOf:
          - type: integer
          - type: 'null'
          title: Length
          description: Maximum number of characters Zoho accepts for this field. Used to constrain extraction
            so updates don't fail Zoho validation.
        data_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Data Type
          description: Zoho's semantic field type (e.g. 'email', 'date', 'datetime'). Mapped to a JSON
            Schema format so extraction produces well-formed values.
        system_mandatory:
          type: boolean
          title: System Mandatory
          description: Whether Zoho requires this field to be present on create/update.
          default: false
      type: object
      required:
      - api_name
      - display_label
      - read_only
      - operation_type
      - json_type
      - tooltip
      title: ZohoFieldSetting
    Record_dict_str__object__:
      properties:
        record_id:
          type: string
          title: Record Id
        values:
          additionalProperties: true
          type: object
          title: Values
      type: object
      required:
      - record_id
      - values
      title: Record[dict[str, object]]
    ZohoAvailableEventsResponse:
      properties:
        events_by_module:
          additionalProperties:
            items:
              $ref: '#/components/schemas/ZohoNotificationEvent'
            type: array
          propertyNames:
            $ref: '#/components/schemas/ZohoCRMModules'
          type: object
          title: Events By Module
      type: object
      required:
      - events_by_module
      title: ZohoAvailableEventsResponse
      description: Available Zoho CRM events grouped by module
    TicketPriority:
      type: string
      enum:
      - High
      - Medium
      - Low
      title: TicketPriority
    EmptyCondition:
      properties:
        condition_type:
          type: string
          const: empty
          title: Condition Type
          default: empty
        evaluated_field_name:
          type: string
          minLength: 1
          title: Evaluated Field Name
      type: object
      required:
      - evaluated_field_name
      title: EmptyCondition
    CreateTicketRequest:
      properties:
        subject:
          type: string
          title: Subject
        description:
          type: string
          title: Description
        name:
          type: string
          title: Name
        phone:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone
        language:
          type: string
          title: Language
          default: English
        department_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Department Id
        priority:
          $ref: '#/components/schemas/TicketPriority'
          default: Medium
        status:
          $ref: '#/components/schemas/TicketStatus'
          default: Open
        channel:
          $ref: '#/components/schemas/TicketChannel'
          default: Phone
      type: object
      required:
      - subject
      - description
      - name
      title: CreateTicketRequest
      description: Request payload for creating a Zoho Desk ticket
    ZohoNotificationCreateResponse:
      properties:
        watch:
          items:
            $ref: '#/components/schemas/_NotificationResponseCreate'
          type: array
          title: Watch
      type: object
      title: ZohoNotificationCreateResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    EventEvaluationConditions:
      properties:
        module_type:
          $ref: '#/components/schemas/ZohoCRMModules'
        conditions:
          items:
            oneOf:
            - $ref: '#/components/schemas/EqualityCondition'
            - $ref: '#/components/schemas/LikenessCondition'
            - $ref: '#/components/schemas/EmptyCondition'
            discriminator:
              propertyName: condition_type
              mapping:
                empty: '#/components/schemas/EmptyCondition'
                equality: '#/components/schemas/EqualityCondition'
                likeness: '#/components/schemas/LikenessCondition'
          type: array
          minItems: 1
          title: Conditions
      type: object
      required:
      - module_type
      - conditions
      title: EventEvaluationConditions
    ZohoNotificationDeleteResponse:
      properties:
        watch:
          items:
            $ref: '#/components/schemas/_NotificationResponseDelete'
          type: array
          title: Watch
      type: object
      title: ZohoNotificationDeleteResponse
    ZohoWebhookData:
      properties:
        events:
          items:
            $ref: '#/components/schemas/ZohoNotificationEvent'
          type: array
          title: Events
        query_params:
          $ref: '#/components/schemas/ZohoWebhookQueryParams'
        extra_conditions:
          anyOf:
          - $ref: '#/components/schemas/EventEvaluationConditions'
          - type: 'null'
          description: Extra conditions that may be injected in the webhook configuration. Allows fine-tuning
            routing different cases to scenarios.
      type: object
      required:
      - events
      - query_params
      title: ZohoWebhookData
      description: Required payload to create a new Zoho webhook
    EqualityCondition:
      properties:
        condition_type:
          type: string
          const: equality
          title: Condition Type
          default: equality
        evaluated_field_name:
          type: string
          minLength: 1
          title: Evaluated Field Name
        expected_field_value:
          type: string
          minLength: 1
          title: Expected Field Value
      type: object
      required:
      - evaluated_field_name
      - expected_field_value
      title: EqualityCondition
    DeskTicketGet:
      properties:
        subject:
          type: string
          title: Subject
        description:
          type: string
          title: Description
        language:
          type: string
          title: Language
        phone:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone
        departmentId:
          anyOf:
          - type: string
          - type: 'null'
          title: Departmentid
        priority:
          $ref: '#/components/schemas/TicketPriority'
          default: Medium
        status:
          $ref: '#/components/schemas/TicketStatus'
          default: Open
        channel:
          $ref: '#/components/schemas/TicketChannel'
          default: Phone
        category:
          anyOf:
          - type: string
          - type: 'null'
          title: Category
        subCategory:
          anyOf:
          - type: string
          - type: 'null'
          title: Subcategory
        id:
          type: string
          title: Id
        ticketNumber:
          type: string
          title: Ticketnumber
        contactId:
          type: string
          title: Contactid
      type: object
      required:
      - subject
      - description
      - language
      - id
      - ticketNumber
      - contactId
      title: DeskTicketGet
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    _NotificationEvent:
      properties:
        channel_expiry:
          type: string
          format: date-time
          title: Channel Expiry
        resource_uri:
          type: string
          title: Resource Uri
        resource_id:
          type: string
          title: Resource Id
        resource_name:
          type: string
          title: Resource Name
        channel_id:
          type: string
          title: Channel Id
      type: object
      required:
      - channel_expiry
      - resource_uri
      - resource_id
      - resource_name
      - channel_id
      title: _NotificationEvent
    TicketChannel:
      type: string
      enum:
      - Phone
      - Email
      - Web
      - Chat
      title: TicketChannel
    LikenessCondition:
      properties:
        condition_type:
          type: string
          const: likeness
          title: Condition Type
          default: likeness
        evaluated_field_name:
          type: string
          minLength: 1
          title: Evaluated Field Name
        expected_field_value:
          type: string
          minLength: 1
          title: Expected Field Value
      type: object
      required:
      - evaluated_field_name
      - expected_field_value
      title: LikenessCondition
    Language:
      type: string
      enum:
      - en
      - ar
      - ur
      title: Language
      description: Language codes in ISO 639-1
    ZohoNotificationEvent:
      type: string
      enum:
      - Leads.create
      - Leads.edit
      - Contacts.create
      - Contacts.edit
      title: ZohoNotificationEvent
    TicketStatus:
      type: string
      enum:
      - Open
      - On Hold
      - Escalated
      - Closed
      title: TicketStatus
    ZohoCallableRecord:
      properties:
        id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Id
        First_Name:
          anyOf:
          - type: string
          - type: 'null'
          title: First Name
        Last_Name:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Name
        Full_Name:
          anyOf:
          - type: string
          - type: 'null'
          title: Full Name
        Phone:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone
        Mobile:
          anyOf:
          - type: string
          - type: 'null'
          title: Mobile
        Email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
      additionalProperties: true
      type: object
      title: ZohoCallableRecord
      description: The subset of a CRM record (Leads, Contacts, ...) needed to place an outbound call.
    ZohoPickListValue:
      properties:
        display_value:
          type: string
          title: Display Value
        id:
          type: string
          title: Id
      type: object
      required:
      - display_value
      - id
      title: ZohoPickListValue
    _WatchResponse:
      properties:
        channel_expiry:
          type: string
          format: date-time
          title: Channel Expiry
        resource_name:
          type: string
          title: Resource Name
        channel_id:
          type: string
          title: Channel Id
        events:
          items:
            $ref: '#/components/schemas/ZohoNotificationEvent'
          type: array
          title: Events
        notify_url:
          type: string
          title: Notify Url
        token:
          type: string
          title: Token
        query_strings:
          additionalProperties:
            items:
              type: string
            type: array
          type: object
          title: Query Strings
          description: This custom field contains the query strings provided in the webhook URL.
      type: object
      required:
      - channel_expiry
      - resource_name
      - channel_id
      - events
      - notify_url
      - token
      title: _WatchResponse
    _NotificationDetails:
      properties:
        events:
          items:
            $ref: '#/components/schemas/_NotificationEvent'
          type: array
          title: Events
      type: object
      required:
      - events
      title: _NotificationDetails
    _NotificationResponseDelete:
      properties:
        code:
          type: string
          const: SUCCESS
          title: Code
        message:
          type: string
          title: Message
        channel_id:
          type: string
          title: Channel Id
      type: object
      required:
      - code
      - message
      - channel_id
      title: _NotificationResponseDelete
    ZohoCRMModules:
      type: string
      enum:
      - Leads
      - Contacts
      - Calls
      title: ZohoCRMModules