Your CRM's POST API feature provides the ability to automatically create new CRM leads using data received from your web forms.
For example, you may have a merchant application web form that is hosted on your website or a lead form that clients fill out such as a "Contact Us" page.
When users submit such forms, you can have the entered form data automatically transfer to the CRM, where a new lead may then be created (or an existing one updated) using the data.
The data collected from web forms can also automatically transition into merchant applications that are ready for on-boarding to your processor.
To connect a web form to the CRM you will need to generate a POST Token URL in the CRM, insert the URL in your website form's Action property, and finally map the web form fields to your CRM lead fields.
An example of a simple web form is shown here:
The four fields shown in the above example can be mapped to four different lead fields (for example the DBA Name, Business Email, Business Phone, and Visitor Comment lead fields) which then populate automatically after the form is submitted.
Linking your web forms to the CRM can be done in minutes.
Below we describe the simple steps to configure, test, and use the POST API feature.
Creating A New POST API Token URL
As the first step, you will need to create a POST API Token URL and copy it into your web form's Action property.
Below is an example of a POST API Token URL (in red) copied in a web form's action property:
<form action="https://demo.iriscrm.com/postleads/t/79bfda5e50445637a9ah9b98554d2aa14" method="POST"
enctype="multipart/form-data">
If you have multiple web forms set up on your website(s), you can create and configure separate Token URLs for each web form.
Here's how to create the POST API Token URL:
1. Navigate to Manage > Administration > POST API > Manage POST Token URLs, select the desired User Group (eg. ISO or SUB ISO in the below example), and click the Create Token button:
2. Select the actions that will take place in the CRM when new data is received from the webform:
You can view the explanations of the actions in the token popup by hovering over the question marks.
The explanations of the token settings are also given in the table below:
| Token Setting | Explanation |
| Site Name | Enter an easily identifiable name for your website form. It doesn't need to be the exact web page name or address. |
| Auto Assign Status | Select a lead status to be assigned to new leads. |
| Auto Assign Group | Select a group to be assigned to new leads. |
| Auto Assign Lead Source | Select a lead source to be assigned to new leads. |
| Auto Assign Campaign | Select a campaign to be assigned to new leads. |
| Auto Assign User (every) | Select users to be assigned to all leads imported from this token. |
| Auto Assign User (round-robin) | Select users to be assigned to the leads imported from this token using the round-robin method. |
| Notify Users | Select users who will be notified on all inbound leads imported from this token. |
| Notification Email Template | Select the email template to notify users of inbound leads imported from this token. Leave blank if you do not wish to send notification emails. |
| Thank You Email Template | Select an email template for sending a 'Thank You' note to the submitter. The email will be sent to the email address retrieved from the web form (if available). If you do not wish to send a 'Thank You' email then do not select a template here. |
| Default Document Label | Select a document label that will be applied to documents imported from this token together with the form data. |
| Success URL |
The Success URL is the URL that the user will be re-directed to upon a successful POST submission. Note that the lead ID number is automatically appended to the Success URL that you specify. For example, if you enter "http://www.isotest.com/result=1" as the success URL, this submitter will be redirected to "http://www.isotest.com/result=1&leadId=123" after they submit the form (where '123' is the lead ID). The lead ID number is provided so that you can use it with your other scripts if needed (eg. when using the Lead API to process a request). You can also insert the '{LEAD_ID}' placeholder in any part of your success URL. For example, the "http://www.isotest.com/{LEAD_ID}" Success URL becomes "http://www.isotest.com/123" after a successful submission. |
| Auto Import |
If checked, all inbound leads will be imported automatically. If unchecked, the inbound leads will first wait for your review in the Incoming POST Data page. |
| Merge Duplicates |
If checked, the POST API will look for a duplicate lead in the CRM whose Special: Email field matches the submitter's email in the web form (the Special: Email field must be mapped to the email field in the Token settings). If a duplicate lead is found, its data will be updated with the new data coming in from the web form. If multiple leads match the email address, the most recently updated lead will be updated with the new POST info and assigned users will be notified (if enabled in their user settings). Additionally, if the Update Status, Update User, and Update Campaign & Lead Source checkboxes have also been checked, then these lead options will be automatically updated according to your Token settings. Note that these three checkboxes are only enabled in the Token settings when the Merge Duplicates checkbox is checked. If the Merge Duplicates option is unchecked, then the duplicate checks are not performed and the POST API will instead create new leads with each new form submission. |
| Visitor Tracking |
Receive knowledge about visitor's page views that took place before a form was submitted. If the Visitor Tracking option is checked, your Token will create the POST Form Example which includes a hidden input field called "visitor_tracking" as shown in the below image: The "visitor_tracking" field must be copied to your web form or otherwise the visitor tracking feature will not work. More Info: Managing Visitor Tracking Sites |
3. Click Add Token. The Token is now created and the Token URL is displayed in a basic POST Form Example:
4. To deploy the token on your website, you have a few options:
1. Replace the opening <form> HTML tag in your web form with the one generated in the POST Form Example. This is the easiest solution but not very secure as the POST URL is visible in the page HTML.
2. Use a code/script that contains the POST token URL to more securely process and submit the data.
3. If using a form editor in your website, there may be an option for entering the POST URL in a setting so that the form data gets submitted to it.
If you enabled the Visitor Tracking feature in your token settings, then you will also need to copy the "visitor_tracking" hidden field in your form.
The remaining hidden fields shown in the POST Form Example are optional.
Mapping Your Web Form Fields To The Lead
After you created a token URL and copied it into your web form, you will need to map the fields from your web form to the desired lead fields.
With the mapping completed, the data from each web form field will flow into the corresponding lead field each time the web form is submitted.
Here's how to configure your web form mappings:
1. Go to the Mapping Lead Fields section, type in the web field's name in the Field box, choose the matching lead field from the Assign To list, and click Assign:
2. As you add new mappings they will be shown in boxes below the selection dropdowns. If you need to delete a mapping, click on the trash icon on that mapping:
See the final section in this article for additional instructions for mapping different types of fields.
Testing Your Token URL
Once your web form code is updated with the POST API Token URL you will need to test your form and ensure it works properly.
Fill in the form on your site with some test data and submit the form.
A new lead record should now appear on the Manage Incoming POST Leads page, and it should show the data you submitted.
If you disabled the Auto Import option in your token settings, then look for the incoming data on the Manage Incoming POST Data page instead.
Review the record to make sure that all of the fields from your web form are appearing correctly in the Lead. If not, you will need to re-check and update your form mapping and then try again.
Spamming Rules for POST API Tokens:
To help stop SPAM-posters on your web forms, the following rules are in place to reject excessive submissions.
- If 100+ records are submitted in a 5 minute period, per IP address, additional records from that IP Address will be rejected for 1 day.
- If 360+ records are submitted in a 1 hour period, per IP address, additional records from that IP Address will be rejected for 1 day.
Field Mapping Notes
Below are some additional notes and instructions for mapping your web form fields to the CRM lead fields:
Finding The Correct Web Form Field Names
A field called "Telephone" in your web form may not be called exactly that in the HTML (it may actually be called something like "phone" or "ph_number" or similar).
When you're creating your field mappings, you will need to enter the HTML names of your web fields and not the field's labels (or the mappings may not function correctly).
Your website administrator can supply the web field names for you, or you can also find the field names yourself by right-clicking on a web form field and choosing the Inspect Element option (in Chrome).
The HTML Elements Panel will then open where you can inspect the form's HTML code and locate the names of the form fields.
In the below example, we can see in the Elements Panel that the correct name of the "Telephone" web form field is "phone":
Mapping Text Fields
No special setup is needed to map text fields other than matching the web form field name to the lead field.
Mapping Dropdowns
If you have a dropdown in your web form, you can map the drop-down to a corresponding lead drop-down in the same way as you would map two text fields.
However, in this case you need to ensure that the web form drop-down options also exist in the lead drop-down.
For example, a web form drop-down called "Entity Type" may contain the following items:
- Sole Proprietorship
- LLC
- Corporation
- Partnership
- Government
With the drop-down configured in this way, the corresponding CRM lead drop-down must also contain the same five options, spelled exactly the same.
If both drop-downs have been configured correctly in this way, and if a user selects "Corporation" on the web form and submits it, then the "Corporation" option in the lead drop-down will be automatically selected.
Mapping Checkboxes
If you have a checkbox in your webform that has a value="1" when checked, it can select the option 1 in a drop-down or check a checkbox in the CRM lead (depending on whether you mapped the web form checkbox to a lead drop-down or a lead checkbox).
Combining Two Fields
If your form has First Name and Last Name fields, but you have a single "Contact Name" field in Merchant Central, you can combine the two values into the single field. Here's how to do it:
1) In the HTML of your form, add a hidden field in between the First and Last Name fields. Here's some example HTML, where the field "namespace" is added with the "hidden" attribute so it does not show on the page.
<label for "fname">First Name</label>
<input type="text" name="fname">
<input type="text" name="namespace" hidden>
<label for "lname">Last Name</label>
<input type="text" name="lname">
2) Map the fname, namespace, and lname fields (or whichever names you used) to your Contact Name field. The order of the mapping does not matter, but they must be in the correct order in your form (see example above).
3) By having the hidden, empty field mapped, a space will be added in between the first and last names, like "John Smith". Otherwise, the Contact Name would show as "JohnSmith".
Tip: The same could be done for other fields that need to be combined, such as an Address that has a Suite, Unit, or Floor number as a separate field in your form.
Mapping Comments
A comments/notes field in your web form can be mapped using the Notes option:
Attaching Files
If your form has a box for e-signature, the image of the signature can be included in the submission, as long as it is converted to Base64 before being sent into the CRM.
Any other files such as PDFs or images can also be sent to the CRM in their standard format.
To set up the POST API Token to accept files with your submissions, enter the file upload's parameter/field name in the Mapping Lead Fields section and choose the Lead File option (at the bottom of the Assign To list):
If you need to send multiple files, there must be separate upload fields for them in your form, with each such field mapped to the Lead File option.
In your web form, make sure to also add the "enctype" attribute, for example:
<form action="https://yourdomain.com/postleads/t/c998" method="POST" enctype="multipart/form-data">
Example: Uploading Files With POST API
Advanced Merging of Lead Info
If you have a multi-page form or you want to send a link to the merchant later to update info, you can use the steps below.
- Create a field in your Merchant Central lead form and set the Special to Lead Primary Key.
- In your web form's HTML, add that as a hidden field.
- When someone uses your web form, you would generate an ID (in your code) on the first page and store that so it continues onto the next page and gets submitted as a field in the POST info to Merchant Central.
- Then when they go to the next page, or it was a simple form and you send them a URL in an email from Merchant Central, you would have that ID included in the URL so that your web page could reference it and send it back with the new submission into Merchant Central.
- That would make whatever information that comes in override the existing lead info, but only if it matches that unique ID that you created.