1. v3
  2. Contacts
  3. POST - 3/contacts/import/configs

Definition

POST - 3/contacts/import/configs

Create a new import configuration.

Required roles: Contacts (write)

When creating an import configuration specifically for the API, you can leave the ColumnMappings empty, they will be automatically filled on the first import.

Request information

The new import configuration

Name

The name of the ImportConfiguration which will be used for your own reference and will also be available in the Tool.


Type string
Additional info
Max length: 50
ContactGroupId

The id of the contact group to which all imported contacts will be linked.


Type integer
Additional info

Obsolete: Contactgroups are no longer available, immediately import your contacts into a survey.
ContactListId

The id of the contact list to which all imported contacts will be linked.


Type integer
SurveySettings

When you would like to add the imported contacts immediately to an existing survey, you can define the SurveySettings to indicate to which survey the contacts should be linked and how they should be processed.


Type ImportSurveyLink
ColumnMappings

When uploading a file using the Tool, you should define all columns in the file and define how they should be imported When using the ImportConfig from the API, you don't have to configure the ColumnMappings.


Type Collection of ImportColumnMapping
Additional info

Not in use for API Imports
EmailMustBeUniqueWithinAccount

Define if an email address should be unique in your entire account. Contacts with the same email address will be updated.


Type boolean
EmailMustBeUniqueWithinGroup

Define if an email address should be unique within your group. Contacts with the same email address within your group will be updated.


Type boolean
EmailMustBeUniqueWithinFile

Define if an email address should be unique within your file/request.


Type boolean
EmailIsRequired

An email address should be available for all contacts.


Type boolean
Additional info

Contacts without email address will result in a ResultCode R0307
DateFormat

The format of all dates within your file. The format is case-sensitive.


Type string
Additional info

y: Year, M: Month, d: Day By default the date format of your account will be used.

, Max length: 10
FirstRow

Indicate which row in the file contains the first line of data


Type integer
Additional info

Not in use for API Imports
FieldDelimiter

Indicate which string is used to seperate the different columns in your file


Type string
Additional info
Max length: 10
RowDelimiter

Indicate which string is used to seperate different lines in your file. Examples: \n, \r


Type string
Additional info
Max length: 10
SendNotificationMail

Allows you to enable email notifications for every import which is executed using this configuration.


Type boolean
IsReusable

Indicates whether this configuration can be reused.


Type boolean
Additional info

If false the configuration won't be available in the API nor the Tool interface.
DefaultLanguageCode

The language code is used if you do not import a language column or for blanks.


Type string
Additional info

3/lookup/surveylanguages
UpdateTypeId

Define how we should handle existing contacts. 1: Update existing contacts within this survey. 2: Always create new contacts.


Type integer
Additional info

3/lookup/importconfigupdatetypes

Sample: 
{
  "Name": "sample string 1",
  "ContactGroupId": 1,
  "ContactListId": 1,
  "SurveySettings": {
    "SurveyId": 1,
    "InvitationDelayInDays": 1,
    "InvitationTime": "00:00:00.1234567",
    "ExpirationAfterDays": 1,
    "ExpirationTime": "00:00:00.1234567",
    "ConsiderCooldownPeriod": true,
    "SurveyCooldownAfterInvitation": 1,
    "SurveyCooldownAfterResponse": 1,
    "AccountCooldownAfterInvitation": 1,
    "AccountCooldownAfterResponse": 1
  },
  "ColumnMappings": [
    {
      "SourceColumnNumber": 64,
      "TargetColumnName": "sample string 2"
    },
    {
      "SourceColumnNumber": 64,
      "TargetColumnName": "sample string 2"
    }
  ],
  "EmailMustBeUniqueWithinAccount": true,
  "EmailMustBeUniqueWithinGroup": true,
  "EmailMustBeUniqueWithinFile": true,
  "EmailIsRequired": true,
  "DateFormat": "sample string 2",
  "FirstRow": 1,
  "FieldDelimiter": "sample string 3",
  "RowDelimiter": "sample string 4",
  "SendNotificationMail": true,
  "IsReusable": true,
  "DefaultLanguageCode": "sample string 7",
  "UpdateTypeId": 1
}
Sample: 
<BaseImportConfig xmlns:i="http://www.w3.org/2001/XMLSchema-instance" z:Id="i1" xmlns:z="http://schemas.microsoft.com/2003/10/Serialization/">
  <ColumnMappings>
    <ImportColumnMapping>
      <SourceColumnNumber>64</SourceColumnNumber>
      <TargetColumnName>sample string 2</TargetColumnName>
    </ImportColumnMapping>
    <ImportColumnMapping>
      <SourceColumnNumber>64</SourceColumnNumber>
      <TargetColumnName>sample string 2</TargetColumnName>
    </ImportColumnMapping>
  </ColumnMappings>
  <ContactGroupId>1</ContactGroupId>
  <ContactListId>1</ContactListId>
  <DateFormat>sample string 2</DateFormat>
  <DefaultLanguageCode>sample string 7</DefaultLanguageCode>
  <EmailIsRequired>true</EmailIsRequired>
  <EmailMustBeUniqueWithinAccount>true</EmailMustBeUniqueWithinAccount>
  <EmailMustBeUniqueWithinFile>true</EmailMustBeUniqueWithinFile>
  <EmailMustBeUniqueWithinGroup>true</EmailMustBeUniqueWithinGroup>
  <FieldDelimiter>sample string 3</FieldDelimiter>
  <FirstRow>1</FirstRow>
  <IsReusable>true</IsReusable>
  <Name>sample string 1</Name>
  <RowDelimiter>sample string 4</RowDelimiter>
  <SendNotificationMail>true</SendNotificationMail>
  <SurveySettings>
    <AccountCooldownAfterInvitation>1</AccountCooldownAfterInvitation>
    <AccountCooldownAfterResponse>1</AccountCooldownAfterResponse>
    <ConsiderCooldownPeriod>true</ConsiderCooldownPeriod>
    <ExpirationAfterDays>1</ExpirationAfterDays>
    <ExpirationTime>PT0.1234567S</ExpirationTime>
    <InvitationDelayInDays>1</InvitationDelayInDays>
    <InvitationTime>PT0.1234567S</InvitationTime>
    <SurveyCooldownAfterInvitation>1</SurveyCooldownAfterInvitation>
    <SurveyCooldownAfterResponse>1</SurveyCooldownAfterResponse>
    <SurveyId>1</SurveyId>
  </SurveySettings>
  <UpdateTypeId>1</UpdateTypeId>
</BaseImportConfig>

Response information

Payload containing a boolean indicating if the config has been created and the new config id or a failure message.


Meta

The metadata such as paging parameters, status code, timestamp,... which are related to this request.


Type MetaData
Data

The actual data returned by the request.


Type UpsertImportConfigResult
Links

HATEOAS related to this object. It wil contain relevant url's such as previous and next page for paged results, create/update/delete action. These url's can be used in your application for the next steps in your application logic.


Type Hateoas

Sample: 
{
  "Meta": {
    "Status": 1,
    "TotalRowCount": 1,
    "Limit": 1,
    "Offset": 1,
    "TotalPageCount": 1,
    "StartRec": 1,
    "StopRec": 1,
    "Timestamp": "2024-12-26T13:31:16.1458138Z",
    "IsFiltered": true
  },
  "Data": {
    "ImportConfigId": 1,
    "Succeeded": true,
    "FailureMessage": "sample string 2"
  }
}
Sample: 
<Payload xmlns:i="http://www.w3.org/2001/XMLSchema-instance" z:Id="i1" xmlns:z="http://schemas.microsoft.com/2003/10/Serialization/">
  <Data>
    <FailureMessage>sample string 2</FailureMessage>
    <Succeeded>true</Succeeded>
    <ImportConfigId>1</ImportConfigId>
  </Data>
  <Meta>
    <IsFiltered>true</IsFiltered>
    <Limit>1</Limit>
    <Offset>1</Offset>
    <StartRec>1</StartRec>
    <Status>1</Status>
    <StopRec>1</StopRec>
    <Timestamp>2024-12-26T13:31:16.1458138+00:00</Timestamp>
    <TotalPageCount>1</TotalPageCount>
    <TotalRowCount>1</TotalRowCount>
  </Meta>
</Payload>

Related Examples

Title
Import contacts in bulk