Skip to main content

Importing Mailing Lists with Transactions

This guide demonstrates the APIs that allow you to import contacts with transactions and obtain import status.

XM Directory​

These APIs can only be used with XM Directory.

The following two APIs are discussed:

Import Mailing List Contacts with Transactions​

The following code example shows how to import contact information with transactions. Before using this API, you need to create a transaction batch. See Create Transaction Batch for more information. Set the batchId property in the code example to the newly created transaction batch ID.

The fields array must contain all of the fields that appear in the transactionData. The contacts array contains contact objects. Its properties are covered in detail in Create Contact In Mailing List.

Code and Qualtrics Support​

Our support team does not offer assistance or consultation on custom coding, but you can always try asking our community of dedicated users. If you’d like to know more about our custom coding services you can commission, please contact your Qualtrics Account Executive.

# Import Mailing List Contacts with Transactions

import os
import requests

# Setting user Parameters
apiToken = os.environ["Q_API_TOKEN"]
dataCenter = os.environ["Q_DATA_CENTER"]
directoryId = os.environ["Q_TA_POOL_ID"]

mailingListId = "CG_6VvXPvmYOwhj0vr"

baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/transactioncontacts".format(dataCenter, directoryId, mailingListId)
headers = {
    "x-api-token": apiToken,
    "Content-Type": "application/json"
    }

data = {
       "transactionMeta": {
         "batchId": "BT_egQrgs9MYtG2mON",
         "fields": [
           "representative",
           "amount",
           "currency"
         ]
       },
       "contacts": [
         {
           "firstName": "John",
           "lastName": "Smith",
           "transactionData": {
             "representative": 123456,
             "amount": "1000.00",
             "currency": "Euro"
           },
           "unsubscribed": True,
           "embeddedData": {
             "city": "Paris",
             "country": "FR"
           }
         },
       ]
     }
   
response = requests.post(baseUrl, json=data, headers=headers)
print(response.text)

The response object contains information on the status of the import, as shown below:

{
    "meta": {
        "httpStatus": "202 - Accepted",
        "requestId": "6a1ad6af-aa3a-4fa6-81f7-6e42f9683cc9"
    },
    "result": {
        "contacts": {
            "unprocessed": []
        },
        "id": "PGRS_eP9Klpfqg6P3fJr",
        "status": "in progress",
        "tracking": {
            "url": "https://azuquatest.qualtrics.com/API/v3/directories/POOL_eDNcdUvmPoWYzPL/mailinglists/CG_6VvXPvmYOwhj0vr/transactioncontacts/PGRS_eP9Klpfqg6P3fJr"
        }
    }
}

The following table provides details about the properties of the response object:

PropertyTypeDescription
contactsObjectContains the unprocessed array containing transactions that were not processed.
idStringThe transaction contacts import status id that identifies this import.
statusStringCurrent status of the import.
trackingObjectContains the url property that returns transaction contacts import status. This is the same endpoint used by the Transaction Contacts Import Status API.

Transaction Contacts Import Status​

The Transaction Contacts Import Status API returns information about the current status of the contact transaction import that was started with the Import Mailing List Contacts with Transactions API. The following code example shows how to obtains the status of a contacts import.

# Import Mailing List Contacts with Transactions

import os
import requests

# Setting user Parameters
apiToken = os.environ["Q_API_TOKEN"]
dataCenter = os.environ["Q_DATA_CENTER"]
directoryId = os.environ["Q_TA_POOL_ID"]

mailingListId = "CG_6VvXPvmYOwhj0vr"
importId = "PGRS_51Fej4DxAXnrniB"

baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/transactioncontacts/{3}".format(dataCenter, directoryId, mailingListId, importId)

headers = {
    "x-api-token": apiToken,
    "Content-Type": "application/json"
    }

response = requests.get(baseUrl, headers=headers)
print(response.text)

The response object provides information about how many contacts and transactions were successfully imported and the import's progress.

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "f8389ab7-7d8c-4084-83db-e9e505ea06ef"
    },
    "result": {
        "contacts": {
            "count": {
                "added": 1,
                "failed": 0,
                "updated": 0
            }
        },
        "percentComplete": 100.0,
        "status": "complete",
        "transactions": {
            "count": {
                "created": 1,
                "failed": 0 
            }
        }
    }
}

The following table details the properties of the response object:

PropertyTypeDescription
contactsObjectContains a count object that consists of three properties. The added number indicates the number of new contacts that were created. The failed value indicates how many contracts could not be imported, and updated counts the number of contacts that were updated (de-duplication matched a contact's email with an existing contact).
percentCompleteNumberValue from 0.0 to 100.0 that indicates how complete the contacts import is.
statusStringWhen complete, this value changes to complete. Use the status instead of percentComplete to determine whether an import is done.
transactionsObjectAn object that contains the count object that consists of a created number, which indicates how many new transactions were imported, and a failed number showing how many transaction imports failed.