--- title: "Custom integration hub for API and events" slug: "api-and-events-integration-hub" updated: 2025-05-22T14:53:42Z published: 2025-05-22T14:53:42Z canonical: "knowledge.lightico.com/api-and-events-integration-hub" --- > ## Documentation Index > Fetch the complete documentation index at: https://knowledge.lightico.com/llms.txt > Use this file to discover all available pages before exploring further. # Custom integration hub for API and events This article explains how to use the custom integration hub for configuring settings that are essential for using the Lightico API and consuming events. > [!TIP] > For full documentation of Lightico API and events, see [Lightico developer center](https://developers.lightico.com/). You can find the **Custom**hub on the **Built-in integrations** tab of the Integrations page in the Lightico Admin Center. ![](https://cdn.document360.io/473bb8c5-ff1b-4930-8109-2321ac6ab967/Images/Documentation/2025-01-15_10-55-48.png) > [!NOTE] > Note > > If you are looking to create a custom integration with an external service, please go to [Build a custom integration](/v1/docs/build-a-custom-integration). --- ## Overview The main sections in this article are as follows: - [Set up a custom integration hub](/v1/docs/api-and-events-integration-hub#set-up-a-custom-integration-hub) - [Generate API credentials](/v1/docs/api-and-events-integration-hub#generate-api-credentials) - [Map fields in your app to Lightico Attributes](/v1/docs/api-and-events-integration-hub#map-fields-to-attributes) - [Define event destinations (webhooks)](/v1/docs/api-and-events-integration-hub#define-event-destinations) --- ## Set up a custom integration hub 1. In the admin center left navigation panel, click **Integrations**. The Integrations page opens. 2. Under **Add New Integration**, click **Custom**. ![](https://cdn.document360.io/473bb8c5-ff1b-4930-8109-2321ac6ab967/Images/Documentation/image(202).png) The Custom integration hub opens. 3. Enter a **Name** (only lower case letters and underscores) and a **Description** for this hub. 4. Click **Save**.![](https://cdn.document360.io/473bb8c5-ff1b-4930-8109-2321ac6ab967/Images/Documentation/2025-01-15_11-00-08.png) The Lightico Integration hub is set up and activated. --- ## Generate API credentials Before sending an endpoint from your system to Lightico, you’ll need to generate credentials for authorization purposes. **To generate API credentials:** 1. In the custom integration hub, click **Generate API Credentials**. You are prompted to enter your Lightico login credentials. 2. Enter your Lightico Username and Password and click **Apply**. ![](https://cdn.document360.io/473bb8c5-ff1b-4930-8109-2321ac6ab967/Images/Documentation/2025-01-13_14-40-50(1).png) The API credentials appear. 3. Click **Save**. ![](https://cdn.document360.io/473bb8c5-ff1b-4930-8109-2321ac6ab967/Images/Documentation/image(204).png) > [!NOTE] > Note > > Take note of the **Client ID** and **API Key**, for authenticating API calls. > [!TIP] > Tips > > - To see the **API Key**, you'll need to provide your Lightico login credentials. > - For the **API Password**, you'll need to click the refresh button, enter a new password, and use this new one in your system. --- ## Map fields to Attributes Mapping fields from your app/platform to Lightico Attributes enables you to do the following: - Fill in digital forms and PDFs with pre-existing data from your platform. - Use your data to affect conditional actions in Workflows. - Update fields in your app with the data obtained during a session. - Enhance intelligent document analyzing. > [!NOTE] > Note > > Field mapping is only supported when creating a session using the API and not with a session initiated by an agent from the agent console. See [Defining a data source](/v1/docs/api-and-events-integration-hub#defining-a-data-source) below. ### Methods of field mapping There are two ways to map fields. You can choose one or the other, depending on your needs: - [**Dynamic mapping**](/v1/docs/api-and-events-integration-hub#dynamic-mapping) - for collaboration session endpoints. - [**Schema mapping**](/v1/docs/api-and-events-integration-hub#schema-mapping) - for Document Analyzer endpoints. ### Dynamic mapping Dynamic mapping is where you establish a link between your app/platform and import objects and fields into Lightico. > [!TIP] > #### Advantages of dynamic over schema mapping > > - Automatic and accurate import and updates of your fields. > - Supported for all Workflows sent by API #### Two step process Dynamic field mapping is accomplished in 2 steps: 1. [Import objects and fields from your app into the custom hub](/v1/docs/api-and-events-integration-hub#import-objects-and-fields-into-the-custom-hub) > [!WARNING] > Requirement > > Importing objects and fields requires you to develop an API response to the import request. This can be done with the help of your Lightico customer service rep. 2. [Map the imported fields to Attributes in the Attributes mapping page of the admin center](/v1/docs/api-and-events-integration-hub#map-the-imported-fields-to-attributes) --- #### Import objects and fields into the custom hub 1. In the **Connectivity**tab of the custom integration hub, enter the URL, username, and password for your app. 2. (optional) To enable the system to check for specific headers (for example, simple authorization), click **Add headers**and define the headers. ![](https://cdn.document360.io/473bb8c5-ff1b-4930-8109-2321ac6ab967/Images/Documentation/image(182).png) 3. In the **Import objects** tab, click **Import now**. ![](https://cdn.document360.io/473bb8c5-ff1b-4930-8109-2321ac6ab967/Images/Documentation/image(184).png) When the import is complete, all the imported objects are shown in the Connectivity tab. --- #### Map the imported fields to Attributes 1. Go to the **Attribute mapping** page in the admin center and find (or create) an Attribute to which you would like to map one of your imported fields. 2. Click the edit icon for the Attribute. ![](https://cdn.document360.io/473bb8c5-ff1b-4930-8109-2321ac6ab967/Images/Documentation/image(185).png) The **Update Attribute** window appears. 3. At the bottom of the window, click **Add source**. ![](https://cdn.document360.io/473bb8c5-ff1b-4930-8109-2321ac6ab967/Images/Documentation/2025-01-05_09-41-13(1).png) The source settings appear. 4. Define the following: 1. **Source**- Name that you gave to the custom integration hub. 2. **Object** - Select the name of the object that contains the field you are mapping. 3. **Field**- Name of the field from your app that you are mapping. 4. **Updatable**- Select this checkbox to use changes made in a Lightico session to update the data in your app. For example, if the customer changes their email address during a Lightico session, the email field will be updated in your app. ![](https://cdn.document360.io/473bb8c5-ff1b-4930-8109-2321ac6ab967/Images/Documentation/2025-01-05_09-53-47.png) 5. Click **Save**. The Attribute is mapped to your app field. 6. Repeat the steps for all relevant fields that were imported from your app. ### Schema mapping Schema mapping is where you manually provide the objects and fields from your app in the form of a JSON schema. > [!NOTE] > Note > > Currently, schema mapping is only supported for Document Analyzer endpoints and not for running a Lightico session. > [!TIP] > #### **Advantages over dynamic mapping** > > - Provide and update fields without a live connection to Lightico > - No development required > - Map Attributes directly from the custom hub --- #### **Map Attributes with a JSON schema** 1. Create a JSON file of all the objects and fields you would like to map. 2. In the **Data schema**tab of the custom integration hub, click **Upload schema**. ![](https://cdn.document360.io/473bb8c5-ff1b-4930-8109-2321ac6ab967/Images/Documentation/image(191).png) A file browser appears. 3. Select the JSON file. ![](https://cdn.document360.io/473bb8c5-ff1b-4930-8109-2321ac6ab967/Images/Documentation/image(190).png) The objects and fields appear in the Data schema tab. Values for the fields are replaced by Attribute dropdowns. ![](https://cdn.document360.io/473bb8c5-ff1b-4930-8109-2321ac6ab967/Images/Documentation/image(194).png) 4. For each field you would like to map, select an Attribute from the dropdown. > [!NOTE] > Note: > > Each field can be mapped to only one Attribute. Conversely, each Attribute can be mapped to only one field in the schema. ![](https://cdn.document360.io/473bb8c5-ff1b-4930-8109-2321ac6ab967/Images/Documentation/image(192).png) 5. Click **Save**. ![](https://cdn.document360.io/473bb8c5-ff1b-4930-8109-2321ac6ab967/Images/Documentation/image(193).png) > [!NOTE] > Note > > You can also map your fields to Attributes from the Attribute mapping page as explained in [Dynamic mapping above](/v1/docs/api-and-events-integration-hub#map-the-imported-fields-to-attributes). ### Defining a data source By default, Lightico identifies data in a session by its Attribute name. If you have mapped your fields to Lightico Attributes, you need to let Lightico know that you want your field names to be the source of the data/field names. Lightico will then translate data coming from your app into Attribute names that can be used in the session. This is done using one of the following API endpoints, depending on what type of action you are performing: - **Adding Dynamic Workflow v28.1** - in the [**Set Attributes for a session**](https://developers.lightico.com/docs/api-reference/kn5nxrzjhaj8p-set-attributes-for-a-session) endpoint, enter the custom hub name in the `source` parameter - **Adding Workflow template**- In the [**Create new session**](https://developers.lightico.com/docs/api-reference/j65cuazjo5e0t-v21-1-create-new-session) endpoint enter the custom hub name in the `sourceName` parameter - **Starting document analysis** - In the [Create document analysis](https://developers.lightico.com/docs/api-reference/bwqwiaeyzmu4e-create-document-analysis)endpoint enter the custom hub name in the `sourcename` parameter > [!WARNING] > Define the value of the `source` or `sourceName` parameter as the name of the custom integration hub where you configured the field mapping. > > For example: > > ```plaintext > "sourceName": "my_custom_mapping_hub" > ``` --- ## Define event destinations Events are Lightico's way of letting you know when something significant occurs in your Lightico account and providing you with information about that occurrence. See [Events](https://lightico.stoplight.io/docs/api-reference/hx4t0ssicfwdy-events) in the Lightico developer center for an explanation of all events. Each type of event notification can be sent to a different destination URL (webhook). In the integration hub, you can define a URL for each of the different events. > [!CAUTION] > Warning > > Lightico permits the use of client-controlled endpoints for integration purposes. Please be aware that Lightico reserves the right to remove any endpoints that utilize free or open webhook site services. This measure is in place to ensure the security of callback data. **To configure event destinations:** 1. Open the **Events** tab in your API integration hub. This tab shows all supported Lightico API events. 2. Click **Expand All** and enter a URL and, where applicable, a Username and Password for each event. 3. You can click **Test Connectivity** to verify that each event URL is valid. ![](https://cdn.document360.io/473bb8c5-ff1b-4930-8109-2321ac6ab967/Images/Documentation/2025-01-13_15-15-08.png) Event destinations are configured. ### Send events to multiple destinations If you need to send events to multiple URLs, you can create more than one API integration hubs and define different webhooks for each one. Each event will be sent to all defined URLs. ![](https://cdn.document360.io/473bb8c5-ff1b-4930-8109-2321ac6ab967/Images/Documentation/2025-01-15_13-48-26.png) ### Send events to specific destinations If you need events for a session to be sent to the webhooks in only one of your configured hubs, you can do so using one of these endpoints: - For a session - [v21.1 Create new session](https://developers.lightico.com/docs/api-reference/j65cuazjo5e0t-v21-1-create-new-session) - For dynamic Workflows - [v28.1 Create new session](https://developers.lightico.com/docs/api-reference/03mjydacjghlr-v28-1-create-new-session) - For Workflow templates - [v21.3 Add Workflow template to a session](https://developers.lightico.com/docs/api-reference/40vk9dqjde9zc-v21-3-add-workflow-template-to-a-session) In the `hubs` object, define `events` as the name of the hub with the relevant webhooks. > [!NOTE] > For example, > > `"hubs": {` > > `    "events": "hub_2"` > > `}` Area of the Lightico platform where you will find all settings, user management, and asset configuration pages. Access to this area is defined by a user's role and permissions. An identifying label that you bind to data in a session that enables you to organize and make use of the data during the session. A user that communicates with end-customers to complete tasks in a Collaboration Room session or a Case Manager case.