Zoho Zia Org Enrichment API

openapi: 3.1.0
info:
  title: Helpcenter Zia Org Enrichment API
  version: 1.0.0
tags:
- name: Zia Org Enrichment
paths:
  /__zia_org_enrichment:
    post:
      operationId: submitOrgEnrichmentRequest
      summary: Trigger organization-level enrichment for a CRM record
      description: Initiates the ZIA organization enrichment process for a specific CRM record. Accepts module name, record ID, and supported fields (name, email, website).
      parameters:
      - name: module
        in: query
        required: true
        schema:
          type: string
          maxLength: 255
          description: CRM module name from which enrichment is triggered.
        description: CRM module name from which enrichment is triggered.
      - name: record_id
        in: query
        required: false
        schema:
          type: string
          maxLength: 19
          description: Unique CRM record ID for which enrichment is requested.
        description: Unique CRM record ID for which enrichment is requested.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body for organization enrichment.
              properties:
                __zia_org_enrichment:
                  type: array
                  description: List of input objects used to trigger organization enrichment.
                  items:
                    type: object
                    description: Organization enrichment input object.
                    properties:
                      enrich_based_on:
                        type: object
                        description: Fields used to identify and enrich the organization.
                        properties:
                          name:
                            type: string
                            description: Name of the organization used for enrichment.
                            maxLength: 255
                          email:
                            type: string
                            format: email
                            description: Email address used to enrich organization details.
                          website:
                            type: string
                            format: website
                            description: Website domain used for organization enrichment.
                        required:
                        - name
                        additionalProperties: false
                    required:
                    - enrich_based_on
                    additionalProperties: false
                  maxItems: 50
              required:
              - __zia_org_enrichment
              additionalProperties: false
      responses:
        '202':
          description: Success Responses
          content:
            application/json:
              schema:
                type: object
                properties:
                  __zia_org_enrichment:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Indicates the scheduling status of the enrichment job
                          enum:
                          - SCHEDULED
                        details:
                          type: object
                          properties:
                            id:
                              type: string
                              description: Unique identifier assigned to the scheduled enrichment job
                              maxLength: 255
                          required:
                          - id
                          description: Additional information about the enrichment job
                          additionalProperties: false
                        message:
                          type: string
                          description: Readable message describing the result of the request
                          maxLength: 255
                        status:
                          type: string
                          description: Indicates whether the request was successful or failed
                          enum:
                          - success
                      required:
                      - code
                      - details
                      - message
                      - status
                      description: List containing organization enrichment job status
                      additionalProperties: false
                    description: Response key
                    maxItems: 50
                required:
                - __zia_org_enrichment
                description: Org Enrichment scheduled successfully
                additionalProperties: false
        '400':
          description: Bad request Responses
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  properties:
                    __zia_org_enrichment:
                      type: array
                      items:
                        type: object
                        properties:
                          code:
                            type: string
                            description: Type of validation error encountered
                            enum:
                            - INVALID_DATA
                            - MANDATORY_NOT_FOUND
                          details:
                            type: object
                            properties:
                              expected_data_type:
                                type: string
                                description: Expected data type of the field, if applicable
                                maxLength: 255
                              api_name:
                                type: string
                                description: The name of the field that triggered the validation error
                                enum:
                                - name
                                - email
                                - website
                                - enrich_based_on
                              json_path:
                                type: string
                                description: JSON path pointing to the exact invalid or missing field.
                                enum:
                                - $.__zia_org_enrichment[0].enrich_based_on.name
                                - $.__zia_org_enrichment[0].enrich_based_on.email
                                - $.__zia_org_enrichment[0].enrich_based_on.website
                                - $.__zia_org_enrichment[0].enrich_based_on
                            required:
                            - api_name
                            - json_path
                            description: Additional information describing the cause of the error
                            additionalProperties: false
                          message:
                            type: string
                            description: Message describing the reason for the error.
                            maxLength: 255
                          status:
                            type: string
                            description: Specifies the status of the request
                            enum:
                            - error
                        required:
                        - code
                        - details
                        - message
                        - status
                        description: List containing error details related to organization enrichment
                        additionalProperties: false
                      description: Response Key
                      maxItems: 50
                  required:
                  - __zia_org_enrichment
                  description: Error Resposne when a mandatory field is missing or a field is invalid.
                  additionalProperties: false
                - type: object
                  properties:
                    __zia_org_enrichment:
                      type: array
                      items:
                        type: object
                        properties:
                          code:
                            type: string
                            description: Error code indicating that the enrichment limit has been exceeded
                            enum:
                            - LIMIT_EXCEEDED
                          details:
                            type: object
                            properties:
                              limit:
                                type: integer
                                description: Maximum enrichment limit allowed
                                format: int32
                              limit_due_to:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    api_name:
                                      type: string
                                      description: Name of the field that contributed to the limit issue
                                      enum:
                                      - enrich_based_on
                                    json_path:
                                      type: string
                                      description: JSON path of the specific field causing the limit breach
                                      enum:
                                      - $.__zia_org_enrichment[0].enrich_based_on
                                  required:
                                  - api_name
                                  - json_path
                                  description: Fields object which caused the limit to be exceeded
                                  additionalProperties: false
                                description: List of fields which caused the limit to be exceeded
                                maxItems: 1
                            required:
                            - limit
                            - limit_due_to
                            description: Additional metadata about the limit violation
                            additionalProperties: false
                          message:
                            type: string
                            description: Readable explanation of the error.
                            maxLength: 255
                          status:
                            type: string
                            description: Status of the request
                            enum:
                            - error
                        required:
                        - code
                        - details
                        - message
                        - status
                        description: Array containing org enrichment responses
                        additionalProperties: false
                      description: Response key
                      maxItems: 1
                  required:
                  - __zia_org_enrichment
                  description: Error Response when limit exceeded
                  additionalProperties: false
                - type: object
                  properties:
                    __zia_org_enrichment:
                      type: array
                      items:
                        type: object
                        properties:
                          code:
                            type: string
                            description: Error indicating that required input fields were missing
                            enum:
                            - EXPECTED_FIELD_MISSING
                          details:
                            type: object
                            properties:
                              expected_fields:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    api_name:
                                      type: string
                                      description: The expected field name
                                      enum:
                                      - name
                                      - email
                                      - website
                                    json_path:
                                      type: string
                                      description: JSON path indicating the location of the missing field
                                      enum:
                                      - $.__zia_org_enrichment[0].enrich_based_on.name
                                      - $.__zia_org_enrichment[0].enrich_based_on.email
                                      - $.__zia_org_enrichment[0].enrich_based_on.website
                                  required:
                                  - api_name
                                  - json_path
                                  description: Fields object expected in enrich_based_on.
                                  additionalProperties: false
                                description: List of fields expected in enrich_based_on.
                                maxItems: 50
                            required:
                            - expected_fields
                            description: Details about the missing expected fields
                            additionalProperties: false
                          message:
                            type: string
                            description: Readable explanation of the error
                            maxLength: 255
                          status:
                            type: string
                            description: Error status indicator
                            enum:
                            - error
                        required:
                        - code
                        - details
                        - message
                        - status
                        description: Response wrapper for organization enrichment
                        additionalProperties: false
                      description: Response key
                      maxItems: 50
                  required:
                  - __zia_org_enrichment
                  description: Error Response when Expected field is missing.
                  additionalProperties: false
                - type: object
                  properties:
                    code:
                      type: string
                      description: Unique error code indicating the type of validation or processing failure
                      enum:
                      - REQUIRED_PARAM_MISSING
                      - INVALID_DATA
                    details:
                      type: object
                      properties:
                        param_name:
                          type: string
                          description: Specifies which parameter caused the error—either because it is missing or invalid
                          enum:
                          - module
                          - record_id
                      required:
                      - param_name
                      description: Provides additional information about the missing or invalid parameter involved in the error
                      additionalProperties: false
                    message:
                      type: string
                      description: Message describing the reason for the failure
                      maxLength: 255
                    status:
                      type: string
                      description: Indicates that the API returned an error response
                      enum:
                      - error
                  required:
                  - code
                  - details
                  - message
                  - status
                  description: Error Response when Required param is missing or invalid.
                  additionalProperties: false
                - $ref: '#/components/schemas/FeatureNotEnableOrNotSupported'
                - type: object
                  properties:
                    code:
                      type: string
                      description: Indicates the type of validation failure. Here, it represents invalid input data.
                      enum:
                      - INVALID_DATA
                    details:
                      type: object
                      properties:
                        maximum_length:
                          type: integer
                          description: Specifies the maximum allowed number of items in the array
                          format: int32
                        api_name:
                          type: string
                          description: The API name of the field where the error occurred.
                          enum:
                          - __zia_org_enrichment
                        json_path:
                          type: string
                          description: JSONPath indicating the exact location in the request where invalid data was found.
                          enum:
                          - $.__zia_org_enrichment
                      required:
                      - maximum_length
                      - api_name
                      - json_path
                      description: Contains detailed information about why the provided data is invalid.
                      additionalProperties: false
                    message:
                      type: string
                      description: A human-readable message describing the validation error
                      maxLength: 255
                    status:
                      type: string
                      description: Indicates that the response represents an error state
                      maxLength: 255
                  required:
                  - code
                  - details
                  - message
                  - status
                  description: Error Response when Feature not enabled or not supported.
                  additionalProperties: false
        '403':
          description: No permission Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoPermission'
      security:
      - iam-oauth2-schema:
        - ZohoCRM.settings.intelligence.CREATE
      tags:
      - Zia Org Enrichment
    get:
      summary: Get Zia Org Enrichment
      description: Retrieve the Zia Org Enrichment records with pagination and filtering options
      operationId: getZiaOrgEnrichment
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Perpage'
      - $ref: '#/components/parameters/Sortby'
      - $ref: '#/components/parameters/Sortorder'
      - $ref: '#/components/parameters/Status'
      responses:
        '200':
          description: List of enrichment jobs returned successfully
          content:
            application/json:
              schema:
                type: object
                description: Response wrapper for organization enrichment jobs list
                additionalProperties: false
                properties:
                  __zia_org_enrichment:
                    type: array
                    description: Array of organization enrichment jobs
                    items:
                      type: object
                      description: Organization enrichment job object
                      additionalProperties: false
                      properties:
                        id:
                          type: string
                          maxLength: 19
                          description: Enrichment job ID
                        status:
                          type: string
                          enum:
                          - SCHEDULED
                          - COMPLETED
                          - DATA_NOT_FOUND
                          - FAILED
                          description: Status of the enrichment job
                        created_time:
                          type: string
                          format: date-time
                          description: Job creation timestamp
                        created_by:
                          type: object
                          description: User who triggered the enrichment job
                          additionalProperties: false
                          properties:
                            id:
                              type: string
                              description: User ID who triggered the job
                              maxLength: 19
                            name:
                              type: string
                              description: Name of the user
                              maxLength: 255
                          required:
                          - id
                          - name
                      required:
                      - id
                      - status
                      - created_time
                      - created_by
                    maxItems: 100
                  info:
                    type: object
                    description: Pagination information
                    additionalProperties: false
                    properties:
                      per_page:
                        type: integer
                        description: Number of records per page
                        format: int32
                        const: 100
                      count:
                        type: integer
                        maximum: 100
                        format: int32
                        description: Total number of records
                      page:
                        type: integer
                        format: int32
                        description: Current page number
                      more_records:
                        type: boolean
                        description: Indicates if more records exist
                    required:
                    - per_page
                    - count
                    - page
                    - more_records
                required:
                - __zia_org_enrichment
                - info
        '204':
          description: No enrichment jobs found to return.
        '400':
          description: Bad responses
          content:
            application/json:
              schema:
                description: 400 responses
                oneOf:
                - $ref: '#/components/schemas/FeatureNotEnableOrNotSupported'
                - $ref: '#/components/schemas/ZiaOrgEnrichmentInvalidParam'
        '403':
          description: No permission Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoPermission'
      security:
      - iam-oauth2-schema:
        - ZohoCRM.settings.intelligence.READ
      tags:
      - Zia Org Enrichment
  /__zia_org_enrichment/{id}:
    get:
      operationId: getOrgEnrichmentById
      summary: Retrieve organization-level enrichment data by enrichment ID
      description: Fetches the enrichment status and enriched organization data for a specific enrichment job using its unique ID. Returns completed, scheduled, or failed enrichment information along with enriched fields such as name, website, email, address, CEO, revenue, employees, social media, and industries.
      parameters:
      - $ref: '#/components/parameters/ZiaOrgEnrichmentId'
      responses:
        '200':
          description: Success Responses
          content:
            application/json:
              schema:
                type: object
                description: Organization level  enrichment data fectched Successfully
                additionalProperties: false
                properties:
                  __zia_org_enrichment:
                    type: array
                    description: List of organization enrichment results.
                    items:
                      type: object
                      description: Organization enrichment result object.
                      additionalProperties: false
                      properties:
                        id:
                          type: string
                          maxLength: 19
                          description: Unique ID for the enrichment record.
                        status:
                          type: string
                          enum:
                          - COMPLETED
                          - SCHEDULED
                          - FAILED
                          - DATA_NOT_FOUND
                          description: Status of the enrichment process.
                        enrich_based_on:
                          type: object
                          description: Input fields used for triggering enrichment.
                          properties:
                            name:
                              type: string
                              description: Organization name used for enrichment
                              maxLength: 255
                            email:
                              type: string
                              format: email
                              description: Email used for enrichment
                              maxLength: 255
                            website:
                              type: string
                              maxLength: 255
                              description: Website used for enrichment
                          additionalProperties: false
                        enriched_data:
                          type:
                          - object
                          - 'null'
                          additionalProperties: true
                          description: contains dynamic properties which should be configured from the configuration settings
                      required:
                      - id
                      - status
                      - enrich_based_on
                      - enriched_data
                    maxItems: 1
                required:
                - __zia_org_enrichment
        '204':
          description: No enrichment data found for the given ID or the job ID is invalid.
        '400':
          description: Bad response
          content:
            application/json:
              schema:
                type: object
                description: Error response when feature is not enabled or not supported.
                properties:
                  __zia_org_enrichment:
                    type: array
                    description: List containing the error details.
                    items:
                      $ref: '#/components/schemas/FeatureNotEnableOrNotSupported'
                    maxItems: 1
                additionalProperties: false
        '403':
          description: No permission Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoPermission'
      security:
      - iam-oauth2-schema:
        - ZohoCRM.settings.intelligence.READ
      tags:
      - Zia Org Enrichment
components:
  parameters:
    Sortby:
      name: sort_by
      in: query
      required: false
      description: Field to sort by.
      schema:
        type: string
        enum:
        - created_time
        description: String specifying the field used for sorting.
    Status:
      name: status
      in: query
      required: false
      description: Filter records by enrichment status.
      schema:
        type: string
        enum:
        - COMPLETED
        - FAILED
        - DATA_NOT_FOUND
        - SCHEDULED
        description: String to filter records by their enrichment status.
    ZiaOrgEnrichmentId:
      name: id
      in: path
      required: true
      description: The unique identifier of the Zia Org Enrichment record
      schema:
        type: string
        maxLength: 255
    Perpage:
      name: per_page
      in: query
      required: false
      description: Number of records per page.
      schema:
        type: integer
        format: int32
        enum:
        - 100
        description: Integer specifying the number of records per page.
    Sortorder:
      name: sort_order
      in: query
      required: false
      description: Sort order (ascending or descending).
      schema:
        type: string
        enum:
        - asc
        - desc
        description: 'String indicating sort order: ''asc'' or ''desc''.'
    Page:
      name: page
      in: query
      required: false
      description: The page number for pagination.
      schema:
        type: integer
        format: int32
        enum:
        - 1
        - 2
        description: Integer specifying the page number for paginated results.
  schemas:
    ZiaOrgEnrichmentInvalidParam:
      type: object
      description: Error response when invalid query parameters are provided in the request
      additionalProperties: false
      properties:
        code:
          type: string
          enum:
          - INVALID_DATA
          description: Indicates invalid input data
        details:
          type: object
          description: Details about the invalid parameter and its allowed values
          additionalProperties: false
          properties:
            param:
              type: string
              enum:
              - status
              - sort_order
              - sort_by
              description: The query parameter that caused the validation error
            supported_values:
              oneOf:
              - type: array
                items:
                  type: string
                  description: Valid value for 'status' parameter
                  enum:
                  - COMPLETED
                  - SCHEDULED
                  - FAILED
                  - RUNNING
                  - DATA_NOT_FOUND
                maxItems: 5
                description: Valid values for 'status' parameter
              - type: array
                items:
                  type: string
                  description: Valid value for 'sort_order' parameter
                  enum:
                  - asc
                  - desc
                maxItems: 2
                description: Valid values for 'sort_order' parameter
              - type: array
                items:
                  type: string
                  description: Valid value for 'sort_by' parameter
                  enum:
                  - created_time
                maxItems: 1
                description: Valid values for 'sort_by' parameter
          required:
          - param
          - supported_values
        message:
          type: string
          maxLength: 255
          description: Human-readable message describing the invalid parameter
        status:
          type: string
          enum:
          - error
          description: Indicates request failure
      required:
      - code
      - details
      - message
      - status
    FeatureNotEnableOrNotSupported:
      type: object
      properties:
        code:
          type: string
          description: Error code indicating whether the enrichment feature is disabled or not supported in the user's license
          enum:
          - FEATURE_NOT_ENABLED
          - FEATURE_NOT_SUPPORTED
        details:
          type: object
          properties: {}
          description: Additional information related to the error. This object is sometimes empty for these error types.
          additionalProperties: false
        message:
          type: string
          description: Human-readable message explaining why the enrichment feature cannot be used
          maxLength: 255
        status:
          type: string
          description: Indicates that the response represents an error
          enum:
          - error
      required:
      - code
      - details
      - message
      - status
      description: Error Response when Feature not enabled or not supported.
      additiona

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho/refs/heads/main/openapi/zoho-zia-org-enrichment-api-openapi.yml