Create Zia Data Enrichment Configuration

Purpose

This API creates a Zia Data Enrichment configuration by mapping permitted enrichment fields to Zoho CRM fields. Before invoking this API, use the Get Data Enrichment Fields Metadata API to identify the supported enrichment fields and valid CRM field mappings.

Endpoints

POST /settings/zia/data_enrichment

Request Details

Request URL

{api-domain}/crm/{version}/settings/zia/data_enrichment

Supported Modules

Leads, Contacts, Accounts, Vendors, and Custom.

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.Zia.enrichment.ALL
(or)
ZohoCRM.Zia.enrichment.READ

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/zia/data_enrichment"
-X POST
-d "@data.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Input JSON

Specify the data_enrichment JSON array root key and include the following required keys to create a Data Enrichment configuration, including mappings between enrichment fields and Zoho CRM fields.

moduleJSON object, mandatory
Specify the module for which you want to create the Data Enrichment configuration. Use the Modules Metadata API to retrieve module API names and IDs.
typestring, mandatory
Specify the type of enrichment.
Possible values:
organization: Organization-level enrichment
input_data_field_mappingJSON array, mandatory
Specify the mapping of enrichment fields to Zoho CRM fields that act as input (trigger) fields.
These fields are used to trigger data enrichment. When you provide values in these CRM fields, Zia uses that input to fetch related data and populate other mapped fields.
Example: If Company is configured as an enrichment field in the Leads module, entering a value in the Company field will trigger enrichment of other fields based on the mapping.
- enrich_fieldJSON object, mandatory
  Specify the enrichment field details. Zia uses this field to search for relevant data over the Internet.
  - namestring, mandatory
    Specify the name of the enrichment field.
  - display_labelstring, optional
    Specify the display label of the field.
  Use the Get Data Enrichment Fields Metadata API to know the allowed enrich fields for mapping with CRM fields.
- crm_fieldJSON object, mandatory
  Specify the CRM field that acts as the trigger.
  - idstring, (either id or api_name is mandatory)
    Specify the unique ID of the CRM field.
  - api_namestring, (either id or api_name is mandatory)
    Specify the API name of the CRM field.
  Providing input to this field triggers data enrichment in the mapped output fields. Use the Get Data Enrichment Fields Metadata API to retrieve valid CRM field IDs and API names.
output_data_field_mappingJSON array, mandatory
Specify the mapping of enrichment fields to Zoho CRM fields that will be updated with enriched data.
When values are entered in the fields specified in input_data_field_mapping, Zia retrieves relevant data and updates the CRM fields defined here.
- enrich_fieldJSON object, mandatory
  Specify the enrichment field details.
  - namestring, mandatory
    Specify the name of the enrichment field.
  - display_labelstring, optional
    Specify the display label of the field.
  Zia fetches data based on this field and enriches the mapped CRM field. Use the Data Enrichment Fields Metadata API to know the allowed enrichment fields.
- crm_fieldJSON object, mandatory
  Specify the CRM field that will receive enriched data.
  - idstring, (either id or api_name is mandatory)
    Specify the unique ID of the CRM field.
  - api_namestring, (either id or api_name is mandatory)
    Specify the API name of the CRM field.
  When enrichment is enabled and Zia finds data, this field will be updated automatically. Use the Data Enrichment Fields Metadata API to retrieve valid CRM field IDs and API names.

Sample Input

Copied{
    "data_enrichment": [
        {
            "module": { //mandatory
                "api_name": "Leads",
                "id": "5725767000000002175"
            },
            "type": "organization", //mandatory
            "input_data_field_mapping": [ //mandatory
                {
                    "enrich_field": { //mandatory
                        "display_label": "Organization Name", //optional
                        "name": "org_name" //mandatory
                    },
                    "crm_field": //mandatory
                    {
                        "api_name": "Company", //Either the "api_name" or the "id" is mandatory
                        "id": "5725767000000002591"
                    }
                },
                {
                    "enrich_field": {
                        "display_label": "Email",
                        "name": "email"
                    },
                    "crm_field": {
                        "api_name": "Email",
                        "id": "5725767000000002599"
                    }
                },
                {
                    "enrich_field": {
                        "display_label": "Website",
                        "name": "org_website"
                    },
                    "crm_field": {
                        "api_name": "Website",
                        "id": "5725767000000002607"
                    }
                }
            ],
            "output_data_field_mapping": [
                {
                    "enrich_field": {
                        "display_label": "Organization Name",
                        "name": "name"
                    },
                    "crm_field": {
                        "api_name": "Company",
                        "id": "5725767000000002591"
                    }
                },
                {
                    "enrich_field": {
                        "display_label": "Primary Email",
                        "name": "primary_email"
                    },
                    "crm_field": {
                        "api_name": "Email",
                        "id": "5725767000000002599"
                    }
                },
                {
                    "enrich_field": {
                        "display_label": "Primary Contact Number",
                        "name": "primary_contact"
                    },
                    "crm_field": {
                        "api_name": "Phone",
                        "id": "5725767000000002601"
                    }
                },
                {
                    "enrich_field": {
                        "display_label": "Secondary Contact Number",
                        "name": "secondary_contact"
                    },
                    "crm_field": {
                        "api_name": "Mobile",
                        "id": "5725767000000002605"
                    }
                }
            ]
        }
    ]
}

Possible Errors

INVALID_DATAHTTP 400
- Invalid data
  Resolution: Specify valid values. Refer to the Request JSON section. Use the Get Data Enrichment Fields Metadata API to retrieve allowed enrichment and CRM fields.
- Invalid field IDs
  Resolution: Specify valid fields(enrich_field and crm_field) IDs. Use the Get Data Enrichment Fields Metadata API to retrieve unique field IDs for mapping.
- Invalid API names for the given fields
  Resolution: Specify valid fields(enrich_field and crm_field) API names. Use the Get Data Enrichment Fields Metadata API to retrieve the API names for mapping.
MANDATORY_NOT_FOUNDHTTP 400
One or more mandatory fields missing
Resolution: Specify all mandatory fields. Refer to the Request JSON section to know the mandatory fields.
NOT_ALLOWEDHTTP 400
- One or more unsupported fields have been used for mapping
  Resolution: Specify only supported or allowed fields in both the enrich_field and crm_field keys within the output_data_fields_mapping and input_data_fields_mapping JSON arrays. Use the Get Data Enrichment Fields Metadata API to identify the supported fields for mapping.
- Trying to map a field that has already been mapped
  Resolution: Each field selected for mapping in both the enrich_field and crm_field keys can only be mapped once. Fields cannot be used for multiple mappings.
EXPECTED_FIELD_MISSINGHTTP 400
One or more expected fields are missing
Resolution: Specify all the expected fields in the input body to create configuration. Refer to the Request JSON section for more details.
INVALID_MAPPINGHTTP 400
Invalid mapping
Resolution: Map the enrich fields with their corresponding CRM fields. Use the Get Data Enrichment Fields Metadata API to see allowed enrich fields along with their corresponding CRM fields for mapping data enrichment configuration.
NO_PERMISSIONHTTP 400
No permission to create Zia Data Enrichment Configuration
Resolution: You do not have permission to create configuration. Contact your administrator.
FEATURE_NOT_ENABLEDHTTP 400
Data enrichment feature is not enabled for your account
Resolution: Enable data enrichment feature or contact your system administrator.
INVALID_REQUEST_METHODHTTP 400
The http request method type is not a valid one
Resolution: You have specified an invalid HTTP method to access the API URL.
Specify a valid request method. Refer to Endpoints section above.
OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: The client does not have a valid scope to create data enrichment configuration. Create a new token with valid scope. Refer to Scope section for details.
AUTHENTICATION_FAILUREHTTP 401
Authentication failed
Resolution: Pass the access token in the request header of the API call.
INVALID_URL_PATTERNHTTP 404
Please check if the URL trying to access is a correct one
Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to the Request URL section for details.
INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in the server. Contact support team.

Sample Response

Copied{
    "data_enrichment": [
        {
            "code": "SUCCESS",
            "details": {
                "created_time": "2024-11-14T03:19:07-08:00",
                "id": "5725767000004541010",
                "created_by": {
                    "id": "5725767000000411001",
                    "name": "Patricia Boyle"
                }
            },
            "message": "Enrichment created successfully",
            "status": "success"
        }
    ]
}