Skip to main content

Using Contact Transactions in XM Directory

This guide discusses the APIs for working with contact transactions. Contact transactions allow you to save information about interactions with contacts (for example, purchase amounts, purchase locations, or whether the transaction occurred online). One use of transactions would be to present different survey questions depending on the data saved with the transaction.

For a tutorial on using contact transactions, see Using Transactions in XM Directory.

Each API requires your XM Directory ID. See Finding Your Qualtrics IDs for more information.

XM Directory Only​

These APIs are only available to XM Directory users.

This guide covers the following APIs:

Create Contact Transactions​

The Create Contact Transactions API allows you to create transactions for one or more contacts. The API allows you to specify the contact, the contact's mailing list, the transaction date, and the key-value data associated with the transaction.

The following code example shows how to create three new transactions associated with one contact. The a, b, and c values are arbitrary values to identify the transaction status in the response object. You can use any value.

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.

# Create Contact Transaction

import requests

# Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATA CENTER"

directoryId = "POOL_12345"

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


data = {
      "a": {
        "mailingListId": "CG_12345",
        "contactId": "CID_23456",
        "transactionDate": "2017-08-27 18:00:00",
        "data": {
            "location": "Seattle"
        }
      },
      "b": {
        "mailingListId": "CG_12345",
        "contactId": "CID_23456",
        "transactionDate": "2017-08-28 18:00:00",
        "data": {
            "location": "New York"
        }

      },
      "c": {
        "mailingListId": "CG_12345",
        "contactId": "CID_23457",
        "transactionDate": "2017-08-29 18:00:00",
        "data": {
            "location": "Chicago"
        }
      }


   }

response = requests.post(baseUrl, json=data, headers=headers)
print(response.text)

The response object contains two objects, createdTransactions for the transactions that were successfully created and unprocessedTransactions for the transactions that failed or are incomplete.

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "d97b2b51-acbe-4dae-afdb-1f1055fea781"
    },
    "result": {
        "createdTransactions": {
            "a": {
                "id": "CTR_12345"
            },
            "b": {
                "id": "CTR_12346"
            },
            "c": {
                "id": "CTR_12347"
            }
        },
        "unprocessedTransactions": {}
    }
}

The following table describes the objects in the response object:

MemberTypeDescription
createdTransactionsObjectThe transaction IDs for the transactions that were successfully created. These IDs can be used to create a transaction batch with Create Transaction Batch.
unprocessedTransactionsObjectTransactions that have not completed processing.

Get Contact Transaction​

The Get Contact Transaction API returns information about the specified transaction. The information includes:

  • the ID of the contact
  • The ID of the mailing list that is associated with the specified transaction.
  • The date and time the transaction occurred.
  • The transaction ID.
  • A data object that contains the transaction data.
# Get Contact Transaction

import requests

#Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATA CENTER"

directoryId = "POOL_123456"
transactionId = "CTR_1234"

baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/transactions/{2}".format(dataCenter, directoryId, transactionId)
headers = {
    "content-type": "application/json",
    "x-api-token": apiToken,
    }

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

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "ef461314-b5ac-4434-9a61-fbe24d45bd6b"
    },
    "result": {
        "contactId": "CID_6h4Y4JDg2zXYYzX",
        "data": {
            "currency": "Euro",
            "spend": "100",
        },
        "mailingListId": "CG_cZ5Xf3ANBJTEoRf",
        "transactionDate": "2017-08-18 20:51:00",
        "transactionId": "CTR_5b9PdrtcZ2ohrOl"
    }
}

The following table describes the information returned:

MemberTypeDescription
contactIdStringThe contact ID that this transaction is associated with.
dataObjectThe transaction data object. It consists of string values representing a user-defined transaction.
mailingListIdStringThe mailing list associated with the specified transaction.
transactionDateStringThe date and time of the specified transaction.
transactionIdStringThe transaction ID.

List Contact Transactions​

The List Contact Transactions API returns information about all of the transactions associated with a contact. The information returned includes the contact ID and mailing list ID that are associated with the transaction, the transaction date and time, and the transaction ID.

Transaction Data​

This API does not return the transactions' data objects by default. If you want the data objects, you will need to add the withData query parameter set to true.

# List Contact Transactions

import requests

#Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATA CENTER"

directoryId = "POOL_12345"
contactId = "CID_1234"

baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/contacts/{2}/transactions".format(dataCenter, directoryId, contactId)
headers = {
    "content-type": "application/json",
    "x-api-token": apiToken,
    }

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

{
  "result": {
    "elements": [
      {
        "transactionId": "CTR_eyQvFrZ11n54Uuh",
        "contactId": "CID_012345678901234",
        "mailingListId": "CG_e888sCAXgOh194x",
        "transactionDate": "2016-11-30 13:15:02",
        "data": {
          "field1": "fieldValue1"
        }
      },
      {
        "transactionId": "CTR_3DzxXfwKBBkAbLT",
        "contactId": "CID_012345678901234",
        "mailingListId": "CG_0CgJ5dzzztIvxIN",
        "transactionDate": "2016-10-12 09:56:25",
        "data": {
          "field2": "fieldValue2"
        }
      }
    ],
    "nextPage": null
  },
  "meta": {
    "httpStatus": "200 - OK",
    "requestId": "623c59ba-6df1-4949-8d91-1ba43c53c445"
  }
}

The returned elements array contains information on every transaction associated with the specified contact. Each object in the elements array contains the following members:

MemberTypeDescription
contactIdStringThe contact ID that the transaction is associated with.
mailingListIdStringThe mailing list ID that the transaction is associated with.
transactionDateStringThe transaction date as yyyy-MM-dd HH:mm:ss.
transactionIdStringThe transaction's ID.
dataobjectThe transaction data object. It consists of string values representing a user-defined transaction

Append Contact Transaction​

The Append Contact Transaction allows you to modify transaction data. Its behavior is slightly different from Update Contact Transaction because it does not allow the transaction date and time to be modified.

The following code example shows how to change values in an existing transaction:

# Append Contact Transaction

import requests

# Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATA CENTER"

directoryId = "POOL_123456"
transactionId = "CTR_123456"

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

data = {
        "data": {
          "type": "NotAStoreVisit",
          "spend": "10.0",
        },
   }

response = requests.post(baseUrl, json=data, headers=headers)
print(response.text)

The response object indicates whether the operation completed successfully, as shown below:

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "d6842628-c198-4c14-892c-16c684808613"
    }
}

The following table shows the results of using the Append Contact Transaction API. The first column shows the operation, such as setting a value to an empty string (""). The second column shows what happens if that operation is applied to values that already exist in the transaction. The third column shows what happens if there is no value of that name already in the transaction.

Set the Value toIf the Value Already ExistsIf the Value Does Not Exist
Empty stringThe value is deleted from transaction.The value is not added to the transaction.
nullThe value is set to blank.The value is not added to the transaction.
Non-empty string.The value is changed to the new string.A new value is created and added to transaction.

For example, you currently have a transaction with the following data:

"data": {
  "currency": "Euro",
  "spend": "100",
}

You invoke Append Contact Transaction with the following data (using None for null in Python):

{
  "currency": "",
  "spend": None,
  "newValue": "new"
}

The resulting transaction will contain the following:

{
  "spend": "100",
  "newValue": "new"
}

The currency value will be removed, the None (null) value will be ignored, and newValue will be set to new.

Update Contact Transaction​

The Update Contact Transaction API allows you to update transaction data and the transaction date and time. The API operates slightly differently than the Append Contact Transaction API.

The following code sample shows how to update an existing transaction's values and its date and time.

# Update Contact Transaction

import requests

# Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATA CENTER"

directoryId = "POOL_12345"
transactionId = "CTR_23456"

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

data = {
        "data": {
          "currency": "Euro",
          "spend": "100.00",
        },
    "transactionDate": "2017-08-18 20:51:00"
   }

response = requests.put(baseUrl, json=data, headers=headers)
print(response.text)

The following response object shows successful completion of the operation:

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "68d7a8c3-f098-42d9-b384-35fa65ff2382"
    }
}

The following table shows how different values affect a transaction. For more information about how to interpret the information in the following table, see Append Contact Transaction above.

Set Value ToIf the Value Already ExistsIf the Value Does Not Exist
Empty stringThe value is changed to empty string.A new value created, added to the transaction, and set to an empty string.
nullThe value is deleted from the transaction.The value is not added to the transaction.
Non-empty stringThe value is changed to the new string.A new value is created and added to the transaction.

Delete Contact Transaction​

The Delete Contact Transaction API deletes an entire contact transaction. The following code example shows how the API can be used to delete one transaction.

# Delete Contact Transaction

import requests

#Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = 'YOUR DATA CENTER'

directoryId = "POOL_123456"
transactionId  = "CTR_123456"

baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/transactions/{2}/".format(dataCenter, directoryId, transactionId)
headers = {
    "content-type": "application/json",
    "x-api-token": apiToken,
    }

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

The following response object shows the successful completion of the Delete Contact Transaction API.

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "d0a303d0-1f29-4e80-9342-f9d13cd1d0c9"
    }
}