Data

The DIY Surveys API 3.1 and later offers the ability to integrate with our custom data import feature of a survey.

Importing Data

Import Data based on a surveys custom import definition. For more information on how to set up a survey's custom data import please see here.

URL: base/Data/Import
Method: POST
{
  "Reference": "SurveyReference/DataImportReference",
  "List": 
    [
        {
            { "RequestID": "1234567890DEFED" },
            { "MobileNumber": "44123456789" },
            { "OrgID": 1010 },
            { "Instance": "ETRERT"},
            { "Campaign": 1242 },
            { "TimeStamp": "2020-02-04T11:47:33.645773+00:00" }
        },
        {
            { "RequestID": "1234567891DEFED" },
            { "MobileNumber": "44123456781" },
            { "OrgID": 1011 },
            { "Instance": "ETRERT"},
            { "Campaign": 1242 },
            { "TimeStamp": "2020-02-04T11:47:33.645773+00:00" }
        }
    ]
}

This is only an example of the custom data. As a developer you need to coordinate with those that set up the survey to agree the custom data to use when importing.

Parameters

Name	Type	Description
Reference	Mandatory	The reference to the surveys data import. This can be obtained when setting up the data import in the DIY Surveys user interface.
List	Mandatory	A list of one or more respondents details that can be exactly mapped to the survey's data import that has been set up.

Returns

[
    {
        "Status": "Success",
        "Title": "",
        "FirstName": "",
        "LastName": "",
        "EmailAddresss": "44123456789",
        "Website": "",
        "DateOfBirth" "1700-01-01T00:00:00.000000",
        "When" "2025-07-14T09:19:18.12323223Z"
    },
    {
        "Status": "OverQuota",
    }
]

Return Values

The return structure is a list, the length of which is the same as the list provided in the POST method. Each entry is a status (and potentially a set of standard data fields) that can be matched to the list provided in the POST.

For a successful impot the entry will contain the following information:

Status	A string containing the word success.
Title	A string representing the title of the respondent. If this has not been provided in the POST it will be blank.
FirstName	A string representing the first name of the respondent. If this has not been provided in the POST it will be blank.
LastName	A string representing the last name of the respondent. If this has not been provided in the POST it will be blank.
MobileNumber	A string representing the mobile number of the respondent. If this has not been provided in the POST it will be blank.
EmailAddress	A string representing the email address of the respondent. If this has not been provided in the POST it will be blank.
Website	A string representing the website of the respondent .If this has not been provided in the POST it will be blank.
DateOfBirth	A date representing the date of birth of the respondent. If this has not been provided in the POST it will be a low value of 1700-01-01.
When	A timestamp representing when an invite is set to be sent out for the respondent.

For a failure the following fields will be returned

Status	A status describing the problem. The value presented here will vary depending on the quality of the data provided, but will indicate an issue with the import.

HTTP Statuses

In addition to the standard responses the following HTTP statuses can be returned:

Status	Description
400	Reference is required for import.
400	No data provided for import.
400	Invalid reference format. Expected format 'survey-reference/data-import-name'.
404	Survey with a unique reference of XXX not found.
404	Process with a unique name XXX not found.
404	Process XXX does not belong to survey YYY. Please contact DIR Surveys Client Support for further help
400	Failed to initialize the import process.
400	An error occurred during the import process, but no specific errors were logged. Please check the import data and try again.