Using Transaction Batches in XM Directory

Transaction batches group transactions for use with distributions; a batch or transaction batch is required to create a transaction batch survey distribution. The APIs discussed in this guide allow you to manage your transaction batches.

XM Directory Only

These APIs are only available to XM Directory users.

The following APIs are discussed:

• Get Transaction Batches in Directory
• Get Transactions in a Batch
• Get Transaction Batch
• Create Transaction Batch
• Delete Transaction Batch
• Add Transactions to a Batch
• Remove Transaction from a Batch

Get Transaction Batches in Directory

The Get Transaction Batches in Directory API returns the batch ID and creation date for all of the transaction batches in the organization's XM Directory.

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.

# Get Transaction Batches in a Directory

import requests

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

directoryId = "POOL_123456"

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

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

The following response object shows the transaction batch information in the elements array. Each result contains the batch's ID and its creation date:

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "ed9e81ee-6b2b-4ec2-9bef-4aac7cc1cd08"
    },
    "result": {
        "elements": [
            {
                "batchId": "BT_123456",
                "creationDate": "2017-10-02 20:15:00"
            },
            {
                "batchId": "BT_123457",
                "creationDate": "2017-10-02 21:30:00"
            },
            {
                "batchId": "BT_123458",
                "creationDate": "2017-10-02 21:30:00"
            },
            {
                "batchId": "BT_123459",
                "creationDate": "2017-10-03 01:00:00"
            },
            {
                "batchId": "BT_123470",
                "creationDate": "2017-10-04 01:00:00"
            }
        ],
        "nextPage": null
    }
}

The elements array contains descriptions of each transaction batch as shown below:

Member	Type	Description
batchId	String	The transaction batch ID.
creationDate	String	The date and time the specified transaction batch was created in yyyy-MM-dd HH:mm:ss format.

Get Transactions in a Batch

The Get Transactions in a Batch API returns information for each transaction in a transaction batch. The information includes the contact ID associated with the transaction, the date the transaction was added to the transaction batch, and the transaction ID.

# Get Transactions in a Batch

import requests

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

directoryId = "POOL_123456"
transactionBatchId = "BT_1234"

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

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

The following response object shows the information returned from the Get Transactions in a Batch API:

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "4a479bb5-d9e4-4d32-982b-f348c2f9a4b5"
    },
    "result": {
        "elements": [
            {
                "contactId": "CID_12345",
                "dateAddedToBatch": "2017-08-28 20:09:13",
                "transactionId": "CTR_23451"
            },
            {
                "contactId": "CID_12346",
                "dateAddedToBatch": "2017-08-28 20:09:13",
                "transactionId": "CTR_23452"
            },
            {
                "contactId": "CID_12347",
                "dateAddedToBatch": "2017-08-28 20:09:13",
                "transactionId": "CTR_23453"
            }
        ],
        "nextPage": null
    }
}

The following table provides details of the objects in the returned elements array:

Member	Type	Description
contactId	String	The ID of the contact that is associated with the specified transaction.
dateAddedToBatch	String	The date and time this transaction was added to the specified transaction batch. Specified in UTC as yyyy-MM-dd HH:mm:ss.
transactionId	String	The ID of the transaction.

Get Transaction Batch

The Get Transaction Batch API returns the creation date of the specified transaction batch. The following code example shows how to use the API.

# Get Transaction Batch

import requests

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

directoryId = "POOL_123456"
transactionBatchId = "BT_2345"

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

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

The response object returns the creation date of the specified transaction batch, as shown below:

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "33ae1496-aeea-4315-9b3f-0564494d1cf3"
    },
    "result": {
        "batchId": "BT_2345",
        "creationDate": "2017-08-28 21:30:00"
    }
}

Member	Type	Description
batchId	String	The transaction batch ID (as requested).
creationDate	String	The creation date and time of the specified transaction batch in the format yyyy-MM-dd HH:mm:ss.

Create Transaction Batch

The Create Transaction Batch API lets you create a transaction batch. You supply an array of transaction IDs and the creation date for the batch.

The following code example shows how to create a transaction batch by providing an array of transaction IDs (transactionIds) and the transaction batch's creation date (creationDate).

# Create Transaction Batch

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}/transactionbatches".format(dataCenter, directoryId)
headers = {
    "x-api-token": apiToken,
    "Content-Type": "application/json"
    }

data = {
  "transactionIds": [
    "CTR_12345",
    "CTR_12346",
  ],
  "creationDate": "2017-09-04 01:00:00"
   }

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

The following response object shows the returned transaction batch ID, which can be used with other APIs such as Create Transaction Batch Survey Distribution.

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "6372b60f-f28c-4072-8f00-878603f9e316"
    },
    "result": {
        "id": "BT_23456"
    }
}

Delete Transaction Batch

To delete a transaction batch you can use the Delete Transaction Batch API. The following code example shows how to delete a transaction batch with the batch ID of BT_123456.

# Delete Transaction Batch

import requests

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

directoryId = "POOL_12345"
transactionBatchId = "BT_123456"

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

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

A successful deletion returns a status code of 200 as shown below:

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "c942cb5d-b8e8-4266-9095-6e899bd22970"
    }
}

Add Transactions to a Batch

To add transactions to an existing transaction batch, you can use the Add Transactions to a Batch API. The following code example attempts to add two transactions (CTR_23456 and CTR_23457) to an existing transaction batch (BT_1234).

# Add Transactions to a Batch

import requests

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

directoryId = "POOL_123456"
transactionBatchId = "BT_1234"

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

data = {
  "transactionIds": [
    "CTR_23456",
    "CTR_23457",
  ],
 }

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

The following response object shows the result object contains two objects, added and failed. The added object contains a collection of other objects that, in turn, contain the transactions that were added to the transaction batch successfully. The failed object contains the objects that could not be added to the transaction batch.

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "b0e4e867-feb3-49b6-8d4c-479e5ba2e5e4"
    },
    "result": {
        "added": {
            "0": {
                "transactionId": "CTR_23456"
            }
        },
        "failed": {
            "1": {
                "error": "InvalidTransactionId",
                "errorMessage": "TransactionId: CTR_23457 not found in DB"
            }

        }
    }
}

Member	Type	Description
added	Object	A collection of objects that contain the transaction IDs of successful additions to the specified transaction batch. Each successful transaction is identified by an index that starts at 0 and is incremented by one for each additional transaction.
failed	Object	Objects that could not be added to the transaction batch. Each object contains error and errorMessage members. The error member is an error code that indicates the problem, and errorMessage is a description of the error.

Remove Transaction from a Batch

The Remove Transaction from a Batch API removes one transaction from the specified transaction batch. The following code example shows how to remove the transaction CTR_1235 from transaction batch BT_2345.

# Remove Transaction from a Batch

import requests

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

directoryId = "POOL_12345"
transactionBatchId = "BT_2345"
transactionId = "CTR_1235"

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

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

A successful deletion returns a 200 response code, as shown below:

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "5fc3f157-ec09-4225-8f01-2463d1158fab"
    }
}