Learn how to use the Netcore CE Contact Import API V5 with common import scenarios.
Contact Import API
Before You Begin
The Contact Import API requires a valid API key to authenticate requests.
| Header | Required | Description | Example |
|---|---|---|---|
api-key | Yes | API key used to authenticate the request. | YOUR_API_KEY |
Content-Type | Yes | Specifies the format of the request body. Use application/json. | application/json |
The Create Import endpoint accepts a JSON request body. The import configuration must be passed inside the data object.
Endpoint: POST {{BASE_URL}}/v5/import/create
Replace {{BASE_URL}} with the base URL for the account's region and YOUR_API_KEY with a valid API key.
Create and Publish a Contact Import
Use this request when a contact file is ready to be imported and processed.
When to use: When the source file is ready for import.
What changes: Set import_type to contact, choose the contact_type, set import_state to publish, and provide the file URL.
Best for: Importing contacts from a CRM, customer database, or another system.
Sample request
curl --location '{{BASE_URL}}/v5/import/create'
--header 'api-key: YOUR_API_KEY'
--header 'Content-Type: application/json'
--data-raw '{
"data": {
"import_type": "contact",
"contact_type": "identified",
"import_state": "publish",
"file_url": "https://example.com/uploads/contacts.csv"
}
}'Save an Import as a Draft
Use this request when the import configuration needs to be saved without immediately starting processing.
When to use: When the import needs to be prepared before publishing.
What changes: Set import_state to draft.
Best for: Preparing an import for review before processing.
Sample request
curl --location '{{BASE_URL}}/v5/import/create'
--header 'api-key: YOUR_API_KEY'
--header 'Content-Type: application/json'
--data-raw '{
"data": {
"import_type": "contact",
"contact_type": "identified",
"import_state": "draft",
"file_url": "https://example.com/uploads/contacts.csv"
}
}'Import Anonymous Contacts
Use this request when the source file contains anonymous contact records.
When to use: When the contact records do not contain identifying information.
What changes: Set contact_type to anonymous.
Best for: Importing anonymous visitor or contact records.
Sample request
curl --location '{{BASE_URL}}/v5/import/create'
--header 'api-key: YOUR_API_KEY'
--header 'Content-Type: application/json'
--data-raw '{
"data": {
"import_type": "contact",
"contact_type": "anonymous",
"import_state": "publish",
"file_url": "https://example.com/uploads/anonymous-contacts.csv"
}
}'Import Identified Contacts
Use this request when the source file contains identified contact records.
When to use: When the file contains contact information such as names or email addresses.
What changes: Set contact_type to identified.
Best for: Importing customer records from a CRM, ecommerce platform, or customer database.
Sample request
curl --location '{{BASE_URL}}/v5/import/create'
--header 'api-key: YOUR_API_KEY'
--header 'Content-Type: application/json'
--data-raw '{
"data": {
"import_type": "contact",
"contact_type": "identified",
"import_state": "publish",
"file_url": "https://example.com/uploads/identified-contacts.csv"
}
}'Ignore New Attributes
Use this setting when the import file contains attributes that are not defined in the system and should be ignored.
When to use: When the source file contains additional attributes that are not required for the import.
What changes: Set ignore_new_attributes to true.
Best for: Importing contact files containing additional attributes that do not need to be processed.
Sample request
curl --location '{{BASE_URL}}/v5/import/create'
--header 'api-key: YOUR_API_KEY'
--header 'Content-Type: application/json'
--data-raw '{
"data": {
"import_type": "contact",
"contact_type": "identified",
"import_state": "publish",
"ignore_new_attributes": true,
"file_url": "https://example.com/uploads/contacts.csv"
}
}'Good to know: The default value is
false. When set tofalse, the API returns a Bad Request error if the file contains attributes that are not defined in the system.
Enable Autocorrect
Use this setting to enable automatic correction of minor errors in the imported data.
When to use: When automatic correction is required during the import process.
What changes: Set autocorrect to true.
Best for: Importing contact data where supported minor errors can be corrected automatically.
Sample request
curl --location '{{BASE_URL}}/v5/import/create'
--header 'api-key: YOUR_API_KEY'
--header 'Content-Type: application/json'
--data-raw '{
"data": {
"import_type": "contact",
"contact_type": "identified",
"import_state": "publish",
"autocorrect": true,
"file_url": "https://example.com/uploads/contacts.csv"
}
}'Good to know: The default value is
false. The OpenAPI specification does not define the exact types of errors that autocorrect can resolve.
Assign Audience Details to an Import
Use this setting when audience IDs need to be associated with the imported contacts.
When to use: When audience information must be included as part of the import request.
What changes: Pass audience_details as an array of objects containing audience IDs.
Best for: Associating imported contacts with the specified audiences.
Sample request
curl --location '{{BASE_URL}}/v5/import/create'
--header 'api-key: YOUR_API_KEY'
--header 'Content-Type: application/json'
--data-raw '{
"data": {
"import_type": "contact",
"contact_type": "identified",
"import_state": "publish",
"file_url": "https://example.com/uploads/contacts.csv",
"audience_details": [
{
"id": [5110]
}
]
}
}'Good to know:
audience_detailsis optional if audience information was already provided during the draft stage.- It is mandatory for UDT imports.
- For UDT imports, the specified audience ID can act as the
udt_id.- The supplied OpenAPI schema defines only the
idproperty. Audience names are not included in the schema.
Configure Email Notifications Using notify_callback
Use this parameter to specify the email addresses that should receive notifications about the import status.
When to use: When email notifications are required for completed or unsuccessful imports.
What changes: Pass notify_callback as a JSON object containing the notify object and an array of email addresses.
Best for: Keeping the relevant stakeholders informed about the import outcome.
Sample request
curl --location '{{BASE_URL}}/v5/import/create'
--header 'api-key: YOUR_API_KEY'
--header 'Content-Type: application/json'
--data-raw '{
"data": {
"import_type": "contact",
"contact_type": "identified",
"import_state": "publish",
"file_url": "https://example.com/uploads/contacts.csv",
"notify_callback": {
"notify": {
"email": [
"[email protected]",
"[email protected]"
]
}
}
}
}'Important:
- Notifications are sent to the configured email addresses when the import completes, whether successful or unsuccessful.
notify_callbacksupports email notification details.- Webhook callbacks and callback URL notifications are not supported by the upstream application.
Combine Optional Import Settings
Multiple optional settings can be included in the same request.
Sample request
curl --location '{{BASE_URL}}/v5/import/create'
--header 'api-key: YOUR_API_KEY'
--header 'Content-Type: application/json'
--data-raw '{
"data": {
"import_type": "contact",
"contact_type": "identified",
"import_state": "publish",
"file_url": "https://example.com/uploads/contacts.csv",
"ignore_new_attributes": true,
"autocorrect": true,
"audience_details": [
{
"id": [5110]
}
],
"notify_callback": {
"notify": {
"email": [
"[email protected]",
"[email protected]"
]
}
}
}
}'Response Example
A successful response includes the request ID, response description, status code, and details about the imported file. It can also identify attributes that are missing from the system.
Sample response
{
"request_id": "019445a8-cb89-7c44-9837-5e90236623c2",
"description": "Ok",
"code": 200,
"data": [
{
"missing_attributes": [
{
"attribute_name": "anzsic06"
},
{
"attribute_name": "Area"
},
{
"attribute_name": "year"
}
],
"file_name": "contacts",
"file_extension": ".csv"
}
]
}Important Notes
- The endpoint accepts
application/jsonrequests. - All import parameters must be included inside the
dataobject. import_type,contact_type,import_state, andfile_urlare required by the supplied schema.- The example uses
contactas the import type. contact_typesupportsanonymousandidentified.- The schema currently defines
publishas the onlyimport_statevalue, although the error response also mentionsdraft. file_urlmust point to a publicly accessible CSV file.ignore_new_attributesandautocorrectare optional Boolean parameters.audience_detailsis an array of objects containing audience IDs.notify_callbackis an optional object containing email notification details.
