Sarj AI Developer API Zoho Integration API

openapi: 3.2.0
info:
  title: Sarj.ai Voice Zoho Integration API
  version: 1.0.0
tags:
- name: zoho-integration
paths:
  /v1/beta/integrations/zoho/authorize:
    get:
      tags:
      - zoho-integration
      summary: Authorize
      operationId: zohoIntegrationAuthorize
      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-integration
      summary: Zoho Webhook
      description: Public webhook API where ZohoCRM dumps its webhook data.
      operationId: zohoIntegrationZohoWebhook
      parameters:
      - name: extra_conditions
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Extra Conditions
      - name: config_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Config Id
      - name: scenario_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Scenario Id
      - name: user_email
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: User Email
      - name: user_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
      - name: organization_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          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-integration
      summary: Get Notifications
      operationId: zohoIntegrationGetNotifications
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZohoNotificationGetResponse'
  /v1/beta/integrations/zoho/automations:
    get:
      tags:
      - zoho-integration
      summary: List Automations
      operationId: zohoIntegrationListAutomations
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ZohoEventAutomation'
                type: array
                title: Response Zohointegrationlistautomations
    post:
      tags:
      - zoho-integration
      summary: Create Automation
      operationId: zohoIntegrationCreateAutomation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ZohoEventAutomationConfig'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZohoEventAutomation'
        '409':
          description: An enabled automation already watches this module for this scenario
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/beta/integrations/zoho/automations/{automation_id}:
    get:
      tags:
      - zoho-integration
      summary: Get Automation
      operationId: zohoIntegrationGetAutomation
      parameters:
      - name: automation_id
        in: path
        required: true
        schema:
          type: string
          title: Automation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZohoEventAutomation'
        '404':
          description: No automation with this id in the organization
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - zoho-integration
      summary: Upsert Automation
      operationId: zohoIntegrationUpsertAutomation
      parameters:
      - name: automation_id
        in: path
        required: true
        schema:
          type: string
          title: Automation Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ZohoEventAutomationConfig'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZohoEventAutomation'
        '404':
          description: The id belongs to another organization
        '409':
          description: An enabled automation already watches this module for this scenario
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - zoho-integration
      summary: Delete Automation
      operationId: zohoIntegrationDeleteAutomation
      parameters:
      - name: automation_id
        in: path
        required: true
        schema:
          type: string
          title: Automation Id
      responses:
        '204':
          description: Successful Response
        '404':
          description: No automation with this id in the organization
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/beta/integrations/zoho/disable-webhooks:
    delete:
      tags:
      - zoho-integration
      summary: Remove Notifications
      operationId: zohoIntegrationRemoveNotifications
      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-integration
      summary: Get Available Events
      description: 'Return the events that can be used for webhooks, for this org''s own modules.


        Returns:

        The subscribable notification events grouped by CRM module, including

        the org''s custom modules.'
      operationId: zohoIntegrationGetAvailableEvents
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZohoAvailableEventsResponse'
  /v1/beta/integrations/zoho/modules:
    get:
      tags:
      - zoho-integration
      summary: Get Modules
      description: 'List the org''s writable CRM modules for the webhook and sink pickers.


        Returns:

        Each module''s api_name with the label Zoho shows for it.'
      operationId: zohoIntegrationGetModules
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZohoModulesResponse'
  /v1/beta/integrations/zoho/field-settings:
    get:
      tags:
      - zoho-integration
      summary: Get Field Settings
      operationId: zohoIntegrationGetFieldSettings
      parameters:
      - name: crm_module
        in: query
        required: false
        schema:
          type: string
          pattern: ^[A-Za-z][A-Za-z0-9_]{0,79}$
          default: Leads
          title: Crm Module
      - 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 Zohointegrationgetfieldsettings
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/beta/integrations/zoho/record:
    get:
      tags:
      - zoho-integration
      summary: Get Record
      description: 'Read a CRM record back over HTTP so the canary can verify its lead update landed.


        Returns:

        The CRM record with its callable fields.


        Raises:

        HTTPException: 404 if no record exists with `record_id` in `module`.'
      operationId: zohoIntegrationGetRecord
      parameters:
      - name: record_id
        in: query
        required: true
        schema:
          type: string
          title: Record Id
      - name: module
        in: query
        required: false
        schema:
          type: string
          pattern: ^[A-Za-z][A-Za-z0-9_]{0,79}$
          default: Leads
          title: Module
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZohoCallableRecord'
        '404':
          description: No record with this id in the module
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/beta/integrations/zoho/revalidate-all-webhooks:
    post:
      tags:
      - zoho-integration
      summary: Revalidate All Notifications
      description: Revalidate notifications for all organizations with Zoho tokens.
      operationId: zohoIntegrationRevalidateAllNotifications
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/beta/integrations/zoho/desk/create-ticket:
    post:
      tags:
      - zoho-integration
      summary: Create Ticket
      description: 'Create a ticket in Zoho Desk for the specified organization.


        Returns:

        The ticket as created in Zoho Desk.'
      operationId: zohoIntegrationCreateTicket
      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:
    _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
    RecordField:
      properties:
        source:
          type: string
          const: record_field
          title: Source
        field:
          type: string
          minLength: 1
          title: Field
          description: Zoho field api_name on the triggering record, e.g. Full_Name
      type: object
      required:
      - source
      - field
      title: RecordField
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ZohoModulesResponse:
      properties:
        modules:
          items:
            $ref: '#/components/schemas/ZohoModuleOption'
          type: array
          title: Modules
      type: object
      required:
      - modules
      title: ZohoModulesResponse
    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:
          type: string
          pattern: ^[A-Za-z][A-Za-z0-9_]{0,79}$
          title: Module
        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]]
    EventEvaluationConditions:
      properties:
        module_type:
          type: string
          pattern: ^[A-Za-z][A-Za-z0-9_]{0,79}$
          title: Module Type
        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
    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
    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.
    ZohoNotificationGetResponse:
      properties:
        watch:
          items:
            $ref: '#/components/schemas/_WatchResponse'
          type: array
          title: Watch
      type: object
      title: ZohoNotificationGetResponse
    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:
          patternProperties:
            ^[A-Za-z][A-Za-z0-9_]{0,79}$:
              items:
                type: string
                pattern: ^[A-Za-z][A-Za-z0-9_]{0,79}\.(create|edit)$
              type: array
          type: object
          title: Events By Module
      type: object
      required:
      - events_by_module
      title: ZohoAvailableEventsResponse
      description: Available Zoho CRM events grouped by module
    _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
    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
    TicketChannel:
      type: string
      enum:
      - Phone
      - Email
      - Web
      - Chat
      title: TicketChannel
    TicketStatus:
      type: string
      enum:
      - Open
      - On Hold
      - Escalated
      - Closed
      title: TicketStatus
    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
    ZohoNotificationDeleteResponse:
      properties:
        watch:
          items:
            $ref: '#/components/schemas/_NotificationResponseDelete'
          type: array
          title: Watch
      type: object
      title: ZohoNotificationDeleteResponse
    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
    ZohoEventAutomationConfig:
      properties:
        module:
          type: string
          pattern: ^[A-Za-z][A-Za-z0-9_]{0,79}$
          title: Module
        events:
          items:
            type: string
            pattern: ^[A-Za-z][A-Za-z0-9_]{0,79}\.(create|edit)$
          type: array
          minItems: 1
          title: Events
        enabled:
          type: boolean
          title: Enabled
        scenario_id:
          type: string
          title: Scenario Id
        language:
          $ref: '#/components/schemas/Language'
          default: ar
        variable_mapping:
          additionalProperties:
            oneOf:
            - $ref: '#/components/schemas/RecordField'
            - $ref: '#/components/schemas/FixedValue_str_'
            discriminator:
              propertyName: source
              mapping:
                fixed: '#/components/schemas/FixedValue_str_'
                record_field: '#/components/schemas/RecordField'
          type: object
          title: Variable Mapping
        extra_conditions:
          anyOf:
          - $ref: '#/components/schemas/EventEvaluationConditions'
          - type: 'null'
      type: object
      required:
      - module
      - events
      - enabled
      - scenario_id
      title: ZohoEventAutomationConfig
    ZohoPickListValue:
      properties:
        display_value:
          type: string
          title: Display Value
        id:
          type: string
          title: Id
      type: object
      required:
      - display_value
      - id
      title: ZohoPickListValue
    TicketPriority:
      type: string
      enum:
      - High
      - Medium
      - Low
      title: TicketPriority
    ZohoModuleOption:
      properties:
        api_name:
          type: string
          pattern: ^[A-Za-z][A-Za-z0-9_]{0,79}$
          title: Api Name
        label:
          type: string
          title: Label
      type: object
      required:
      - api_name
      - label
      title: ZohoModuleOption
      description: A module the org can point a webhook or a writeback sink at.
    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
    _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:
            type: string
            pattern: ^[A-Za-z][A-Za-z0-9_]{0,79}\.[a-z_]+$
          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
    FixedValue_str_:
      properties:
        source:
          type: string
          const: fixed
          title: Source
        value:
          type: string
          title: Value
        is_encrypted:
          type: boolean
          title: Is Encrypted
          default: false
      type: object
      required:
      - source
      - value
      title: FixedValue[str]
    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
    ZohoEventAutomation:
      properties:
        module:
          type: string
          pattern: ^[A-Za-z][A-Za-z0-9_]{0,79}$
          title: Module
        events:
          items:
            type: string
            pattern: ^[A-Za-z][A-Za-z0-9_]{0,79}\.(create|edit)$
          type: array
          minItems: 1
          title: Events
        enabled:
          type: boolean
          title: Enabled
        scenario_id:
          type: string
          title: Scenario Id
        language:
          $ref: '#/components/schemas/Language'
          default: ar
        variable_mapping:
          additionalProperties:
            oneOf:
            - $ref: '#/components/schemas/RecordField'
            - $ref: '#/components/schemas/FixedValue_str_'
            discriminator:
              propertyName: source
              mapping:
                fixed: '#/components/schemas/FixedValue_str_'
                record_field: '#/components/schemas/RecordField'
          type: object
          title: Variable Mapping
        extra_conditions:
          anyOf:
          - $ref: '#/components/schemas/EventEvaluationConditions'
          - type: 'null'
        id:
          type: string
          title: Id
        organization_id:
          type: string
          title: Organization Id
        sarj_user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Sarj User Id
        channel_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Channel Id
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - module
      - events
      - enabled
      - scenario_id
      - id
      - organization_id
      - created_at
      - updated_at
      title: ZohoEventAutomation
    Language:
      type: string
      enum:
      - en
      - ar
      - ur
      title: Language
      description: Language codes in ISO 639-1
    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
    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.