JSON integration

Feature snapshot

Summary:
The JSON Integration in LeadConduit enables you to format and deliver outbound lead data as a structured JSON payload by mapping your flow’s fields into a nested format using dot notation. Before you get started with creating your own delivery step, you should check out the integration landing page to see if ActiveProspect has already created one that fits your needs. If you cannot find what you are looking for, then please continue to read this post on how to perform this integration.

Key benefits:

• Delivers data in a hierarchical and organized JSON structure
• Supports complex mapping scenarios including nested objects, arrays, and hardcoded static values
• Enhances compatibility with modern APIs and recipient systems that require precise JSON formatting

Typical use cases:

• Delivering leads to customer CRMs, marketing platforms, or custom endpoints that require JSON input
• Configuring custom outbound integrations where data must be arranged in nested structures
• Implementing token‐authenticated API calls that need dynamic payload formatting

How the JSON integration works

The JSON Integration operates by allowing you to specify exactly how each LeadConduit field is represented within the outbound JSON body. By employing dot notation (e.g., mapping a lead’s first name as lead.first_name), you can create nested objects that mirror the structure expected by modern APIs and external systems. The integration supports both dynamic field mapping and hardcoded values, ensuring every property is accurately positioned within the overall JSON payload.

Step‑by‑step instructions

1. Gather required information
   The first step is to gather the required information such as:

   • Posting documentation
   • The API endpoint URL
   • Describe how the data format should be
   • Describe how the response format should be
   • Any credential that is needed

2. Log in and select your flow:
   Access your LeadConduit account, navigate to the “Flows” tab, and choose the flow where you want to implement the JSON Integration.

3. Add a recipient (delivery) step:
   Edit Flow, click “Add to Flow” and select “Integration”. Then choose or search for the “JSON” integration type from the available options.

   

4. Name and configure the step:
   Provide a descriptive name (e.g., “My custom CRM system”) and click on “Next”.

   

5. Specify the authentication type (if any):
   Select the type of authentication that should be used (if required) and click on “Next”.

   

6. Configure integration settings:
   Under URL, enter your API endpoint URL (e.g., https://api.example.com/lead). Under Data, provide a sample JSON body if available.

   

7. Configure response parsing:
   If you know your recipient’s response format and its content options, you can configure your JSON recipient to parse each lead’s response to identify whether the recipient has accepted or rejected the lead and, in the case of rejected leads, extract the rejection reason (if the recipient supplies it). You can find this information in the recipient’s posting instructions, or you can send test leads to the recipient and examine the resulting responses.

   

   Additional options are available in the field mapping section after completing the initial configuration.

8. Choose what to do in case of failure responses:
   In this step, you can choose whether a lead should continue to the next step after the JSON recipient or stop processing if the response is a failure. If you choose to stop processing, a filter step will be automatically added after the JSON recipient.

   

9. Map LeadConduit fields to JSON properties:
   If you have provided an example JSON body in the previous steps, you will be asked to map any fields LeadConduit has recognized from the body.

   Follow the instructions within the modal to map any dynamic values (using #) or static values (by typing them directly) within each field to map them to the JSON recipient step.

   

10. Map any additional JSON properties:
    Open the “Field Mappings” section within the newly created JSON step. For each field you wish to send, select the corresponding LeadConduit field on the left and choose “JSON Property” on the right. Enter the dot notation path (for example, map “first_name” to lead.first_name, “address_1” to address.line1, and “phone_1” to phones.0.number). You can also select the HTTP method (POST, PUT, DELETE, or PATCH; default: POST), and input any other details that might be required.

    

11. Save and test your flow:
    Save your flow and submit a test lead. Verify the outbound JSON payload in the test lead’s event details to ensure the nested structure and mappings are correct.

Expected result:
The test lead’s event details will display a JSON payload structured with the proper nested objects and arrays, confirming that all mappings have been correctly applied.

Validation & monitoring (optional)

• Test the setup: Submit a test lead after configuring the JSON Integration and review the raw JSON in the Events Dashboard for proper structure and field placement.
• Where to monitor?: Check the LeadConduit Events Dashboard to monitor the outbound JSON payload and validate mapping success.

Best practices

• Use clear and consistent dot notation: Ensure that each nested JSON property is mapped using exact case-sensitive dot notation as outlined in the recipient’s API requirements.
• Map all required and static fields: Cross-reference the recipient’s documentation to ensure all necessary fields are mapped, and use hardcoded values when constant data is required.
• Test incrementally: When working with complex nested structures or arrays, map and test one field at a time, verifying each addition with JSON validation tools before proceeding further.

Troubleshooting

Frequently Asked Questions (FAQ)

What is JSON Integration in LeadConduit?

JSON Integration is a feature that allows you to deliver outbound lead data as a structured JSON payload by mapping your LeadConduit fields into nested JSON objects using dot notation.

Why should I use JSON Integration instead of other formats?

Many modern APIs and external systems require data in a specific JSON format with nested objects and arrays; JSON Integration ensures your data is structured correctly, improving compatibility and reducing errors in data delivery.

How can I verify that my JSON mappings are set up correctly?

After configuring your mappings, submit a test lead and inspect the generated JSON payload in the Events Dashboard. The structure should match the recipient’s requirements, and any mapping errors will be highlighted in the troubleshooting section.

How should a posting document look like?

An example posting document should have the following details:

• API Endpoint: https://my_test_AP_endpoint

• Data Format:

  

• Response Format:

  

All of the information in the example posting document is useful for LeadConduit configuration and is the minimum requirement. Also, this example, assumes that the API endpoint doesn’t require any credentials.

Can I use Bearer authorization in my JSON recipient?

Yes, you can generate Bearer authorization tokens for API services with ease by selecting that option in the authentication type step from the recipient creation modal and following the steps below:

1. Authentication: Choose Bearer Token as the type of authentication you would like to use within your JSON step; and type the API Token required by the recipient system to generate the Bearer Token

   

2. Set up JSON delivery: In this step, you should configure your JSON delivery as previously explained in this article; for these guidelines, we will use the Create Contact endpoint from Voxie’s API as an example.

   

3. Response parsing: In this configuration step, you can specify how request outcomes should be recognized if provided by the recipient system; in this case, we will specify how Voxie’s API supplies error responses.

   

4. Filtering: Next, you can decide whether to stop your lead from moving to succeeding steps in your Flow in case the recipient system provides a failure response.

   

5. Map fields: As the last step of these configuration screens, you can map the fields specified in the JSON body previously provided.

   

6. Edit fields mappings: Now that our step has been created, we can specify the data mappings required for retrieving new Bearer tokens for the recipient’s system API:

   • Authentication URL: This is the URL from the recipient’s system API to which the Token will be requested: For Voxie’s API, we will use https://app.voxie.com/api/v3/teams/{{Voxie’s Team ID}}/issue-personal-access-token

   • Authentication Header: Depending on the recipient’s system API requirements, you might need to specify request headers for the authentication request; in this case, we will specify the following ones for Voxie’s API:

     • Authorization: Bearer TOKEN
TOKEN or ACCESS_TOKEN keywords will be used as a placeholder and replaced by the token provided in the Authorization step of the initial integration configuration

   • Authentication Property: As with the Authentication Header, you might need to specify some parameters to be submitted in the request’s body; in this case, we will specify the following ones for Voxie’s API:

     • name: Voxie Bearer Token
       This parameter is used as the name identifier of the token by Voxie’s API
     • scopes.0: contacts:manage
     • scopes.1: contacts:read
       These scopes are required by Voxie’s API so that the token can be used for creating or updating contacts

   • Authentication Token Path: You can map this field to specify the JSON dot-notation path used to find the access token; the final element will become the name of the credential field; by default, it is set to accessToken, which is the requirement for Voxie’s API; if for instance, the API you want to configure provides the following response with the token:

     {
        "access_token": "long_token_string_here",
        "token_type": "bearer",
        "expires_in": 86399
     }
     

     You should have the following mapping:

     

   • Header: These are the headers that will be used in each request; with the following mapping, we will specify how the token retrieved with the previous mappings will be submitted to Voxie’s API:

     • Authorization: Bearer TOKEN
       TOKEN will be overwritten with the actual Token retrieved with the authentication request

       

     • Notice that you should type the parameter provided by the API system you’re connecting, so if the API provides the token in the authentication request as ACCESS_TOKEN, you should type that value instead

       

Does the integration handle token expiration when using Bearer authorization?

Once the initial token is obtained, the integration will use it for subsequent requests. If a request fails due to token expiration (such as a 401 or 403 error), a new token will be generated and the failed request will be retried.

Are there any other custom input variables that I can use with Bearer authorization?

Yes, the following are configuration options (typically not collected with lead data):

Glossary

• json-catalog.png100 KB
• json-name.png90 KB
• json-authentication.png90 KB
• json-configuration.png90 KB
• json-response-parsing.png100 KB
• json-filter.png90 KB
• json-mapping.png100 KB
• json-step-mappings.png200 KB
• json-sample-payload.jpg100 KB
• json-sample-response.jpg30 KB
• json-bearer-authentication.png80 KB
• json-bearer-payload.png200 KB
• json-bearer-parsing.png200 KB
• json-bearer-mappings.png200 KB
• json-bearer-mapping.png10 KB
• json-bearer-token.png10 KB
• json-bearer-fields.png200 KB