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.

Note. This page was previously titled Import API Mapping. It's still in the same place but is now titled Contact API Import Mapping.

Page controls

ControlDescription
Active / Archived / AllSwitches the templates list between active templates, archived templates, or all templates.
NewCreates a new API import template. The new template will not appear in the templates list until it has been saved.
CloneCreates 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.
UndoReverts any unsaved changes made to the selected template.
SaveSaves 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

FieldDescription
Name*The name of this API import template. Use something descriptive so it can be identified in the list.
DescriptionAn 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 PriorityWhen 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.

OptionDescription
Specified ListAll data from this import is added to a single, fixed list. Select the destination list from the List dropdown.
Create New List Per ImportA new list is created each time an import runs using this template.
Create New List Per DayA 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:

FieldDescription
List To CloneEach 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

FieldDescription
Response URLA 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 FormatSets the format of the API request and response, either XML or JSON.
Call InfoConfigures 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

SettingDescription
Delete Existing ContactsWhen enabled, all existing contacts on the destination list are deleted before the new import is processed.
Keep Existing CallbacksKeeps the existing contacts that have callbacks, along with their callbacks, instead of deleting them. Only visible when Delete Existing Contacts is enabled.
Validate Email AddressesWhen enabled, checks that email addresses in the import are in a valid format.
Add Leading ZeroWhen enabled, a leading zero is automatically added to any phone numbers that are missing one.
Remove Non-DigitsWhen enabled, any non-numeric characters (such as +, - and #) are stripped from phone numbers on import.
Minimum Phone Number LengthAny 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 LengthAny 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 DigitsRemoves 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 ContactWhen 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 CategoriesSelect 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.
Note. Deleting existing contacts is irreversible. Deleted records cannot be recovered, so use Delete Existing Contacts with caution.

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.

ScopeDescription
File uploadedChecks for duplicates within the import file only.
Dedupe against the destination listChecks against records already on the import destination list.
Dedupe against additional listsChecks against specific lists you select.
Global (entire database)Checks across all records on the system.
ActionDescription
Keep existingRetains the existing record and rejects the incoming duplicate.
Keep newReplaces the existing record with the incoming one.
Reset olderResets the existing record's call attempts, making it eligible to dial again, and rejects the incoming record.

Advanced Settings

SettingDescription
Default Skill GroupSets 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 DataFlushes 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 ZoneWhen 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 ZoneSelect the time zone to tag the leads with. Only visible when Use Static Time Zone is enabled.
Calling CodePrepends a calling code to imported numbers where required. Typically used for international numbers imported without a country dialling prefix.
Enable Import ExpiryWhen 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 OptionChoose 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 DateSet the specific date the data will expire (at midnight). Only visible when Expire Option is set to a specific date.
Expire In DaysSet 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.

FieldDescription
File headerThe field name as it appears in your API data, for example a CSV column header.
Field nameThe corresponding standard field in MaxContact that this data should be mapped to.
Ignore secondary mappingWhen 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.

FieldDescription
Secondary tableSelect the custom data table on the system to map secondary fields to.
File headerThe field name as it appears in your API data.
Field nameThe corresponding field in the selected secondary data table.

Related articles