Contact API Import Mapping
The Contact API Import Mapping page is where you configure the settings and field mappings used by your API lead imports. Each configuration is saved as a template, which your API integration references when sending data into the system.
To access it, go to Data > Data Handling > Contact API Import Mapping.
For full details on the API integration itself, see the Lead Management API article.
Page controls
| Control | Description |
|---|---|
| Active / Archived / All | Switches the templates list between active templates, archived templates, or all templates. |
| New | Creates a new API import template. The new template will not appear in the templates list until it has been saved. |
| Clone | Creates a copy of the currently selected template with all its settings and mappings intact. Useful when adding a new import that is similar to an existing one. |
| Undo | Reverts any unsaved changes made to the selected template. |
| Save | Saves any changes made to the selected template. |
Templates
The left-hand panel lists the API import templates configured on your system, filtered by your selected view. Select a template to view and edit it in the right-hand panel, where its settings are split across the General and Mapping tabs.
General tab
The General tab controls how the API import processes incoming data, covering list options, data handling, deduplication, phone number formatting and Do Not Contact checking. These settings mirror those available in the manual Import Leads process.
Status
Use the Status toggle at the top of the tab to change a template from active to archived. Archiving templates you no longer use helps you manage and maintain the templates active on your system.
Details
| Field | Description |
|---|---|
| Name* | The name of this API import template. Use something descriptive so it can be identified in the list. |
| Description | An optional description to help distinguish this template from others on the system. |
| Supplier* | Select the supplier associated with this import. If the required supplier does not appear in the dropdown, select Add Supplier to the right of the field to add a new one. |
| User* | Select the system user account designated for API imports. A dedicated user with its own username and password should already be set up on your system for this purpose. Select the option to the right of the field to open the selected user on the CTU page. |
| Set as High Priority | When enabled, pushes this import to the front of the processing queue. Particularly useful for web lead imports where speed of contact is important. |
* Required field
List Options
Tick one of the following options. The fields that appear next depend on the option you select.
| Option | Description |
|---|---|
| Specified List | All data from this import is added to a single, fixed list. Select the destination list from the List dropdown. |
| Create New List Per Import | A new list is created each time an import runs using this template. |
| Create New List Per Day | A new list is created once per day for all imports using this template on that day. If a list whose name contains the prefix was already created today, that list is reused instead of creating another. |
When you select Create New List Per Import or Create New List Per Day, two more fields appear:
| Field | Description |
|---|---|
| List To Clone | Each new list is created as a copy of the selected list, so it keeps the same settings. |
| List Name (Prefix) | Each new list is named with the prefix you set here. |
API Response
| Field | Description |
|---|---|
| Response URL | A URL the system sends a POST request to once an import has completed or failed. The format of the response (JSON or XML) is determined by the Response Format setting. |
| Response Format | Sets the format of the API request and response, either XML or JSON. |
| Call Info | Configures what agents see in the right-hand panel of Contact Hub during a call. This is free text. Use double curly brackets to reference lead fields dynamically, for example Name: {{first_name}} {{last_name}}. |
Data Handling
| Setting | Description |
|---|---|
| Delete Existing Contacts | When enabled, all existing contacts on the destination list are deleted before the new import is processed. |
| Keep Existing Callbacks | Keeps the existing contacts that have callbacks, along with their callbacks, instead of deleting them. Only visible when Delete Existing Contacts is enabled. |
| Validate Email Addresses | When enabled, checks that email addresses in the import are in a valid format. |
| Add Leading Zero | When enabled, a leading zero is automatically added to any phone numbers that are missing one. |
| Remove Non-Digits | When enabled, any non-numeric characters (such as +, - and #) are stripped from phone numbers on import. |
| Minimum Phone Number Length | Any phone number with fewer digits than this value will be rejected on import. Verify your data before setting this value to avoid discarding valid records. |
| Maximum Phone Number Length | Any phone number with more digits than this value will be rejected on import. Verify your data before setting this value to avoid discarding valid records. |
| Truncate Extra Digits | Removes any digits after the selected Maximum Phone Number Length. Only visible when Maximum Phone Number Length is set to anything other than Ignore. |
| Check Do Not Contact | When enabled, each number in the import is compared against your Do Not Contact lists. Any matching numbers are excluded from the import. |
| Do Not Contact Categories | Select which Do Not Contact categories to check against. IVR, Imported and Requested are available by default. Only visible when Check Do Not Contact is enabled. |
Deduplication
Enable Dedupe (Phone Numbers), Dedupe (Email Addresses), or both to check for duplicate records. Then choose the scope of the check and the action to take when a duplicate is found.
| Scope | Description |
|---|---|
| File uploaded | Checks for duplicates within the import file only. |
| Dedupe against the destination list | Checks against records already on the import destination list. |
| Dedupe against additional lists | Checks against specific lists you select. |
| Global (entire database) | Checks across all records on the system. |
| Action | Description |
|---|---|
| Keep existing | Retains the existing record and rejects the incoming duplicate. |
| Keep new | Replaces the existing record with the incoming one. |
| Reset older | Resets the existing record's call attempts, making it eligible to dial again, and rejects the incoming record. |
Advanced Settings
| Setting | Description |
|---|---|
| Default Skill Group | Sets a default Outbound Skill Group for the imported leads. Useful if some or all of the leads in your import have no Skill Group specified. Opt for None if you are assigning Skill Groups directly in your import. Only visible if your system has Outbound Skill-Based Routing enabled. For more information, see the Outbound Skill-Based Routing articles. |
| Clear Fetched Data | Flushes campaigns, clearing any leads sitting in the dialler buffer waiting to be called. Use this alongside deduplication to prevent the same contact being called twice, once from the buffer and once from the newly imported record. |
| Use Static Time Zone | When enabled, all leads from this import are tagged with a specific time zone, ensuring they are only dialled within the appropriate calling hours for that region. Most UK-only operations do not need this enabled. |
| Define Time Zone | Select the time zone to tag the leads with. Only visible when Use Static Time Zone is enabled. |
| Calling Code | Prepends a calling code to imported numbers where required. Typically used for international numbers imported without a country dialling prefix. |
| Enable Import Expiry | When enabled, sets an expiry date on the imported data. At midnight on the expiry date, all leads from this import, along with any associated callbacks, are automatically removed from the system. This is useful for short-term campaigns, as the data is removed without manual cleanup. |
| Expire Option | Choose between Expire on a specific date or Expire in a number of days from the import date. Only visible when Enable Import Expiry is enabled. |
| Expire On Date | Set the specific date the data will expire (at midnight). Only visible when Expire Option is set to a specific date. |
| Expire In Days | Set the number of days from the import date after which the data will expire. Only visible when Expire Option is set to a number of days. |
List Data Manager Templates
Add List Data Manager templates to run automatically on the imported lists after each import completes. The templates run in the order listed, from top to bottom. Drag a template to change the order.
Mapping tab
The Mapping tab connects the fields in your API data to the corresponding fields in MaxContact. This ensures incoming data is stored correctly and displayed to agents during calls.
Primary Mapping
Maps your API data fields to the standard lead fields in MaxContact (for example, mapping an incoming firstname field to the MaxContact First Name field). Select the + button to add a new mapping row.
| Field | Description |
|---|---|
| File header | The field name as it appears in your API data, for example a CSV column header. |
| Field name | The corresponding standard field in MaxContact that this data should be mapped to. |
| Ignore secondary mapping | When unticked (default), secondary field mapping is also applied. Tick this to skip secondary mapping entirely for this template. |
Secondary Mapping
Maps your API data fields to a secondary (custom) data table on the system. This works in the same way as primary mapping but targets bespoke fields rather than the standard lead table. Select the + button to add a new mapping row.
| Field | Description |
|---|---|
| Secondary table | Select the custom data table on the system to map secondary fields to. |
| File header | The field name as it appears in your API data. |
| Field name | The corresponding field in the selected secondary data table. |


