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. additionalProperties: false NoPermission: type: object properties: code: type: string description: Error code indicating that the user lacks the required permissions to perform the operation. enum: - NO_PERMISSION details: type: object properties: {} description: Contains additional information about missing permissions. This object may be empty additionalProperties: false message: type: string description: Human-readable message explaining that the user does not have permission to access this feature maxLength: 255 status: type: string description: Indicates that the response represents an error enum: - error required: - code - details - message - status description: Error response returned when the user does not have permission to access this feature. additionalProperties: false securitySchemes: iam-oauth2-schema: $ref: ./Common.json#/components/securitySchemes/iam-oauth2-schema x-entity: Helpcenter