Form POST integration

Feature Snapshot

Summary:
Form POST integration is an outbound delivery method in LeadConduit that sends lead data to a recipient’s API endpoint using an HTTP POST request with the content type application/x‑www‑form‑urlencoded, URL‑encoding the data before transmission.

Key Benefits:

• Uses a widely supported standard HTTP POST format
• Automatically URL‑encodes data to ensure safe transmission
• Easily configurable via LeadConduit’s visual field mapping interface

Typical Use Cases:

• Delivering leads to systems that expect web form submissions
• Integrating with custom APIs not covered by built‑in integrations
• Configuring custom recipient steps when a specific posting instruction is required

How the Form POST Integration works?

Step‑by‑Step Instructions

1. Log into LeadConduit and Open Your Flow:
   Log into your LeadConduit account and navigate to the flow where you want to add the integration.

2. Add a New Recipient Step:
   In the flow editor, click on Add to Flow > Integration. In the search field, type “Custom” and select the LeadConduit custom integration option.

3. Name Your Integration:
   Enter a descriptive name (e.g., “Mail Delivery via Form POST”) that clearly identifies its purpose. The best practice is to give every recipient a unique, meaningful name. Optionally, select whether you are sending to your own system or another company.

4. Select the Integration Type:
   Choose Custom Form from the integration types list to indicate that the delivery method will be a Form POST.

5. Enter the POST URL:
   In the field mapping screen, add the recipient’s API endpoint URL; for example, URL → https://api.converzate.com/v1/user. This URL is specified in the recipient’s submission documentation.

6. Configure Request Headers:
   Add header mappings by selecting Header from the dropdown. Include required headers; for example X‑API‑Key → YOUR_API_KEY

7. Map Request Parameters:
   For each parameter required by the recipient, map LeadConduit fields to the Form POST parameters and include any static parameters as needed; for example, map the lead’s email to the “email” parameter as follows: email → email

8. Configure Response Parsing:
   Add response parsing mappings to direct LeadConduit on how to interpret the recipient’s API response.

   A valid lead submission will receive a response such as the following:

   <?xml version="1.0" encoding="utf-8"?>
   <Response>
       <IsValid>True</IsValid>
       <ResponseCode>NoError</ResponseCode>
       <ResponseDetail>The lead was posted successfully</ResponseDetail>
       <LeadId>57820f7f-3e79-481d-8774-fbbc8e6246f6</LeadId>
   </Response>
   

   An invalid lead submission will receive a response such as the following:

   <?xml version="1.0" encoding="utf-8"?>
   <Response>
       <IsValid>False</IsValid>
       <ResponseCode>DuplicateLead</ResponseCode>
       <ResponseDetail>The lead provided is already in our system</ResponseDetail>
   </Response>
   

   Following those responses as an example, you should create the following response mappings:

   • Outcome Search Path → /Response/IsValid/text()
   • Outcome Search Term → True for a successful lead delivery
   • Reason Path → /Response/ResponseCode/text() or /Response/ResponseDetail/text() to capture error details.

9. Position the Recipient Step Appropriately:
   Drag and drop the new recipient step in the flow sequence to ensure it executes in the correct order.

10. Save and Test the Integration:
    After configuring all headers, parameters and response parsing. Save your flow modifications and submit a test lead. Verify that LeadConduit sends a properly formatted Form POST request with URL‑encoded parameters and that the response from the recipient (e.g., XML with <IsValid>True</IsValid>) is parsed correctly.

    Tip for test leads: Before testing a new delivery in an existing flow that is already processing many leads, you can limit the leads that enter to a particular source or email reserved for tests with Step Criteria entered on the step.

11. Filter on the outcome:
    Finally, your response parsing won’t have any effect on the lead unless you have a means to evaluate the success/failure of your new delivery and stop the lead if it has failed, which is usually desired. This is accomplished by adding a Filter step.

    Click on Filter from the Add to Flow dropdown menu. A step will be added to the end of the flow. Click to expand it. Configure it to stop processing if your delivery step’s Outcome is not a Success.

Expected Result:
The Custom Recipient step sends a Form POST request to the specified API endpoint with correctly URL‑encoded parameters. A successful API response (such as an XML response with <IsValid>True</IsValid>) will result in the lead delivery status being recorded as successful in LeadConduit’s event log.

Validation & Monitoring (optional)

• Test the Setup:
   Submit test leads and check LeadConduit’s Events page to ensure that the POST request is sent correctly and the response is parsed as expected.

• Where to Monitor?:
   Review Recipient Event logs and dashboards within LeadConduit that display delivery status and any error messages returned by the recipient’s API.

Best Practices

• Double‑Check Posting Documentation:
   Always verify the recipient’s submission instructions to ensure that parameter names, headers, and required value formats are correct.

• Use Hardcoded Values Judiciously:
   For constants like API keys, project IDs, or configuration values, use hardcoded mappings to reduce the chance of errors.

• Maintain Consistent Naming Across Steps:
   Name your integration and mapping entries clearly to aid in troubleshooting and flow organization.

• Test in a Controlled Environment:
   Before deploying to production, test your integration with sample leads to confirm that both the outbound request and response parsing work as intended.

Troubleshooting

Frequently Asked Questions (FAQ)

What is the Form POST integration used for?

It is used to send lead data via an HTTP POST request with URL‑encoded parameters, making it ideal for APIs that accept form-style submissions.

Why is Form POST integration important?

Form POST integration leverages a standard web form submission method that is broadly supported. It ensures safe and reliable delivery of lead data by automatically encoding parameters, and it allows for easy configuration using LeadConduit’s mapping interface.

How do I use the Form POST integration?

To use it, add a Custom Recipient step to your flow, choose the Custom Form integration type, enter the API endpoint URL and required headers, map your lead data fields to the recipient’s parameters, configure response parsing, save the flow, and test the integration with sample leads.

Is there a content-type header assigned by default by the Form POST integration?

Yes. The integration assignes application/x-www-form-urlencoded by default as the Content-Type.

Glossary

• form-post-mapping.png200 KB