Contact Import: Sample Requests

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.

HeaderRequiredDescriptionExample
api-keyYesAPI key used to authenticate the request.YOUR_API_KEY
Content-TypeYesSpecifies 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 to false, 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_details is 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 id property. 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_callback supports 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/json requests.
  • All import parameters must be included inside the data object.
  • import_type, contact_type, import_state, and file_url are required by the supplied schema.
  • The example uses contact as the import type.
  • contact_type supports anonymous and identified.
  • The schema currently defines publish as the only import_state value, although the error response also mentions draft.
  • file_url must point to a publicly accessible CSV file.
  • ignore_new_attributes and autocorrect are optional Boolean parameters.
  • audience_details is an array of objects containing audience IDs.
  • notify_callback is an optional object containing email notification details.