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

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

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

Sample Request

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

Request JSON

  • data_enrichmentJSON array, mandatory

    Contains the details required to create a data enrichment configuration and map it to CRM fields.

    • moduleJSON object, mandatory

      Specifies the ID and API name of 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

      The type of enrichment.
      Possible values: 
      organization: Organization-level enrichment
      personal: People-level enrichment

    • input_data_field_mappingJSON array, mandatory

      The mapping of enrich fields with fields in Zoho CRM. These enrich fields are the triggers based on which data is enriched in other fields. For example, if you have configured "Company" as the enrich field in the Leads module, then, while creating or updating a lead, if you input a value to the Company field, data in other fields will be automatically populated with enriched data based on the mapping. 
       

      • enrich_fieldJSON object, mandatory

        The name and display label of the enrich field. Zia will look for data about this field over the Internet. Use the Get Data Enrichment Fields Metadata API to know the allowed enrich fields for mapping with CRM fields.
        For the "enrich_field" key, the "name" key is mandatory.

      • crm_fieldJSON object, mandatory

        The unique ID and API name of the field in CRM. Input to this field triggers data enrichment in fields specified in output_data_field_mapping. 
        Use the Get Data Enrichment Fields Metadata API to retrieve the allowed unique IDs and API names of the CRM fields for mapping. Either ID or API name is mandatory.

    • output_data_field_mappingJSON array, mandatory

      The mapping of enrich fields with fields in Zoho CRM. These fields in CRM will be enriched based on data available over the Internet whenever values are input for the fields specified in "input_data_field_mapping".

      • enrich_fieldJSON object, mandatory

        The name and display label of the enrich field. Zia will look for data about this field over the Internet and enriches data in the mapped field. 
        Use the Get Data Enrichment Fields Metadata API to know the allowed enrich fields for mapping with CRM fields.
        For the "enrich_field" key, the "name" key is mandatory.

      • crm_fieldJSON object, mandatory

        The unique ID, name, and API name of the field in CRM. When enrichment is enabled and Zia finds data, the relevant fields in CRM will get updated. Either ID or API name is mandatory. Use the Get Data Enrichment Fields Metadata API to retrieve the allowed unique IDs and API names of the CRM fields for mapping. Either ID or API name is mandatory.

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
  • 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. Ensure you use only the fields listed in the response. If unsupported fields are used, the system will return a "NOT_ALLOWED" error response.
    • 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.

  • FEATURE_NOT_SUPPORTEDHTTP 400

    Data enrichment is not available for your edition of CRM
    Resolution: Data enrichment is available only for the Enterprise and Ultimate editions of CRM. Upgrade your edition or contact support@zohocrm.com.

  • 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 above.

  • 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 above.

  • 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"
        }
    ]
}