This article provides comprehensive documentation on the Audience Import API for CXI (Communicate XI). It covers the creation, retrieval, updating, and deletion of audience imports, as well as the management of asynchronous import jobs.

The API allows users to upload CSV files containing employee data, create audience imports, track the progress of import jobs, and handle any errors that may occur during the import process.

Key features include creating and managing audience imports, retrieving status updates on import jobs, and accessing detailed information about import failures.

Audience Import

CXI UI	Description
	An audience import is an object that represents every CSV file that is uploaded to CXI in order to import employees’ data. This audience import object by itself just indicates that a new file has been uploaded to CXI and all employees contained in this file were imported as Audience Members.Example:Company has created manually or through with a system a CSV file containing all employee data.This file EmployeesList.csv with a custom name (in this case “Employees List“) is sent using CXI Public API endpoint.This audience data is available in the UI through Journey Settings → Audience Creation and Management → Create New → Targeted AudienceBelow it is listed the new audience import by its name “Employees List“
	Once an audience import is available to be selected, a new Audience can be created to be used in a Journey or Communicate Messages.Example:Set a descriptive name for the Audience, in this case, “Audience from Employee List“Select the new audience import, in this case “Employees List“Verify information looks correct (columns, number of rows, etc.) in the previewOptionally one or more filters can be added to select a portion of the AudienceClick on Save button to create a new Audience based on “Employees List“ audience import. Note:If a csv file from an audience import is updated, all audiences created from this audience import will be updated as well.

The audience import object

This is an object representing a CSV file uploaded by yourself. You can retrieve an individual audience import, as well as list all audience imports currently on your CXI account.

https://api.guidespark.com/public-api/audience-imports

Attributes

Element	Description
id (uuid)	Unique identifier for the audience import object.
name (string)	A user-friendly name for the file.
fileName (string)	A filename for the CSV file.
status (string)	Current audience import status. One ofpending, in_progress, completed, or failed.
importType (string)	The type of the imported file (csv).
fieldNames (array of strings)	List of file headers from csv file
emailFieldName (string)	The name of one of the file headers to be used to store email addresses.
mobilePhoneFieldName (string)	The name of one of the file headers to be used to store mobile phone numbers.
nameFieldName (string)	The name of one of the file headers to be used to store names. This can be useful for storing employee names to be used for personalization during communication delivery.
uniqueIdFieldName (string)	The name of one of the file headers to be used to store a way to identify uniquely an employee.
asyncJobId (uuid)	Unique identifier of an asynchronous job related to this audience import. During creation or update this can provide additional information during import process.
createdAt (timestamp)	Timestamp at which the object was created
membersUpdatedAt (timestamp)	Timestamp at which audience members related to this audience import were updated
updatedAt (timestamp)	Timestamp at which the object was updated

Endpoints

POST   /public-api/audience-imports
GET    /public-api/audience-imports/:id
PUT    /public-api/audience-imports/:id
GET    /public-api/audience-imports
DELETE /public-api/audience-imports/:id

Create an audience import

To upload a CSV file to CXI Public API, you’ll need to send a request of type
‘multipart/form-data’. The request should contain the file you would like to upload, as well as the parameters for creating a new audience import.

POST /public-api/audience-import

Purpose: Create an audience import is the first step to import Employees data to CXI and later create a specific audience.

Request headers

Accept REQUIRED	application/json
X-GSCC-Api-Key REQUIRED	This API Token key should be previously generated.

Parameters

TIPS:

• Add a descriptive name for the audience import
• Make sure the csv file to be uploaded has the right content and it is not corrupted.
• Provide email and phone number fields to extend communication channels with your employees. Also, remember to set at least one of these fields otherwise there won’t be a way to communicate with this employee.
• Provide name field to have better results for all your communications. Personalized messages increased your chances to have better results.
• Provide unique Id field name if you have a way to identify uniquely an employee through Employee ID from your HR system or another identifier.

file REQUIRED	A CSV file to upload. The file should be encoded in UTF-8.
name REQUIRED	Name of the audience import displayed in CXI.
emailFieldName OPTIONAL	The name of one of the file headers to be used to store email addresses. Required if ‘mobilePhoneFieldName’ is not specified
mobilePhoneFieldName OPTIONAL	The name of one of the file headers to be used to store mobile phone numbers. Required if ’emailFieldName’ is not specified
nameFieldName OPTIONAL	Optional parameter to be used for personalize different communication with employees, it must be a name of one of the file headers to be used to store names.
uniqueIdFieldName OPTIONAL	Optional parameter in case there is a way to uniquely identify an employee, it must be a name of one of the file headers to be used to store employee ids.

Example request with curl

curl --location --request POST 'https://api.guidespark.com/public-api/audience-imports' \
--header 'X-GSCC-Api-Key: mKGBXn_H8Qf5MKWVrewesw' \
--form 'name="Employees List"' \
--form 'emailFieldName="Email"' \
--form 'mobilePhoneFieldName="Mobile Number"' \
--form 'nameFieldName="First Name"' \
--form 'file=@"/path/to/a/EmployeesList.csv"'

Returns: A new audience import object. Otherwise, this call returns an error.

Example response

{  
"data": {
    "id": "13b2eaf3-48c2-444b-ae0e-a1950a891eaf", 
   "name": "Employees List",
    "fileName": "EmployeesList.csv",
    "status": "pending",
    "importType": "csv",
    "fieldNames": null,
    "emailFieldName": "Email",
    "mobilePhoneFieldName": "Mobile Phone",
    "nameFieldName": "First Name",
    "uniqueIdFieldName": null,
    "asyncJobId": "a42d7a38-b76b-4a2d-9205-4663481475bd",
    "createdAt": "2020-10-16T20:20:40.631Z",
    "membersUpdatedAt": null,
    "updatedAt": "2020-10-16T20:20:40.725Z"
  }
}

Common Errors

• Provide an invalid API Token key
• Leave empty name for audience import
• Provide an empty/corrupted file
• Provide one field name that don’t correspond to any of csv file headers

Retrieve an audience import

Retrieves an audience import with the given ID.

GET /public-api/audience-import/:id

Purpose: Retrieve information from an audience import to verify elements such as name, file name, headers, or last time it was updated. Also, it includes ‘asyncJobId’ which is useful to verify additional information related to the import process.

Request headers

Accept REQUIRED	application/json
X-GSCC-Api-Key REQUIRED	This API Token key should be previously generated.

Query Parameters

TIP: Make sure the provided ID is correct.

id REQUIRED

ID of audience import

Example request with curl

curl --location --request GET 'https://api.guidespark.com/public-api/audience-imports/13b2eaf3-48c2-444b-ae0e-a1950a891eaf' \
--header 'X-GSCC-Api-Key: mKGBXn_H8Qf5MKWVrewesw'

Returns: An audience import object if a valid audience import ID was provided. Returns an error otherwise.

Example response

{
  "data": {
    "id": "13b2eaf3-48c2-444b-ae0e-a1950a891eaf",
    "name": "Employees List",
    "fileName": "EmployeesList.csv",
    "status": "completed",
    "importType": "csv",
    "fieldNames": [
      "First Name", "Last Name", "Email", "Department", "Role", "Mobile Number", "Start Date", "Office City"    
],
    "emailFieldName": "Email",
    "mobilePhoneFieldName": "Mobile Phone",
    "nameFieldName": "First Name",
    "uniqueIdFieldName": null,
    "asyncJobId": "a42d7a38-b76b-4a2d-9205-4663481475bd",
    "createdAt": "2020-10-16T20:20:40.631Z",
    "membersUpdatedAt": "2020-10-16T20:20:45.123Z",
    "updatedAt": "2020-10-16T20:20:40.725Z"
  }
}

Common Errors

• Provide an invalid API Token key
• Provide an invalid audience import ID

Update an audience import

Updates the specified price by setting the values of the parameters passed. Any parameters not provided are left unchanged. To upload a csv file to CXI Public API, you’ll need to send a request of type ‘multipart/form-data’.

PUT /public-api/audience-import/:id

Purpose: Update information from an audience import. Any parameters not provided are left unchanged. This is pretty convenient in case audience import is already referenced by one or more audiences to reflect the latest changes.

Request headers

Accept REQUIRED	application/json
X-GSCC-Api-Key REQUIRED	This API Token key should be previously generated.

TIP: Make sure the provided ID is correct.

Query Parameters

id REQUIRED

ID of audience import

Parameters

TIPS:

• If name is provided make sure it has a descriptive name and never leave it empty, otherwise don’t pass this parameter.
• If a field name is provided make sure it is part of csv file headers
• If csv file is provided make sure it has the right content and it is not corrupted. Also, there will be a new async job ID to perform the import process.
• Unique Id field name can only be defined during Create endpoint, it is not available to be set in Update

file OPTIONAL	A CSV file to upload. The file should be encoded in UTF-8.
name OPTIONAL	Name of the audience import displayed in CXI.
emailFieldName OPTIONAL	The name of one of the file headers to be used to store email addresses. Required if ‘mobilePhoneFieldName’ is not specified
mobilePhoneFieldName OPTIONAL	The name of one of the file headers to be used to store mobile phone numbers. Required if ’emailFieldName’ is not specified
nameFieldName OPTIONAL	Optional parameter to be used for personalizing different communication with employees, it must be a name of one of the file headers to be used to store names.

Example request with curl

curl --location --request PUT 'https://api.guidespark.com/public-api/audience-imports/13b2eaf3-48c2-444b-ae0e-a1950a891eaf' \
--header 'X-GSCC-Api-Key: mKGBXn_H8Qf5MKWVrewesw' \
--form 'name="Employees List (Updated)"' \
--form 'file=@"/path/to/a/EmployeesList2.csv"'

Returns: The newly updated audience import object if the call succeeded. Otherwise, this call returns an error, such as missing parameters or an error in the file.

Example response

{
  "data": {
    "id": "13b2eaf3-48c2-444b-ae0e-a1950a891eaf",
    "name": "Employees List (Updated)",
    "fileName": "EmployeesList2.csv",
    "status": "pending",
    "importType": "csv",
    "fieldNames": [      "First Name", "Last Name", "Email", "Department", "Role", "Mobile Number", "Start Date", "Office City"    
],
    "emailFieldName": "Email",
    "mobilePhoneFieldName": "Mobile Phone",
    "nameFieldName": "First Name",
    "uniqueIdFieldName": null,
    "asyncJobId": "3f713c0d-96a0-4f40-a4f3-694d1b3e944c",
    "createdAt": "2020-10-16T20:20:40.631Z",
    "membersUpdatedAt": "2020-10-16T20:20:45.123Z",
    "updatedAt": "2020-10-16T20:20:40.725Z"
  }
}

Common Errors

• Provide an invalid API Token key
• Provide an invalid audience import ID
• Leave empty name for audience import
• Provide an empty/corrupted file
• Provide one field name that doesn’t correspond to any of CSV file headers

List all audience imports

Returns a list of audience imports that are part of your account.

GET /public-api/audience-import

Purpose: List all available audience imports for an account that API Token has access to

Request headers

Accept REQUIRED	application/json
X-GSCC-Api-Key REQUIRED	This API Token key should be previously generated.

Parameters

No parameters.

Example request with curl

curl --location --request GET 'https://api.guidespark.com/public-api/audience-imports' \
--header 'X-GSCC-Api-Key: mKGBXn_H8Qf5MKWVrewesw'

Returns: A list of all audience imports. Each entry in the array is a separate audience import object. If there are no audience imports, the resulting array will be empty. Otherwise, this call returns an error, such as invalid API Token key.

Example response

{
"data": {
"audienceImports":
[{
"id": "13b2eaf3-48c2-444b-ae0e-a1950a891eaf",
"name": "Employees List",
"fileName": "EmployeesList.csv",
"status": "completed",
"importType": "csv",
"fieldNames": [
"First Name", "Last Name", "Email", "Department", "Role", "Mobile Number", "Start Date", "Office City"
],
"emailFieldName": "Email",
"mobilePhoneFieldName": "Mobile Phone",
"nameFieldName": "First Name",
"uniqueIdFieldName": null,
"asyncJobId": "a42d7a38-b76b-4a2d-9205-4663481475bd",
"createdAt": "2020-10-16T20:20:40.631Z",
"membersUpdatedAt": "2020-10-16T20:20:45.123Z",
"updatedAt": "2020-10-16T20:20:40.725Z"
},
{
"id": "82eebd5b-9469-4141-bb40-ef0a880f2479",
"internalName": "List of Managers",
"name": "ManagersList.csv",
"status": "completed",
"importType": "csv",
"fieldNames": [
"Employee ID", "First Name", "Last Name", "Email", "Department", "Role", "Mobile Number", "Start Date", "Office City"
],
"emailFieldName": "Email",
"mobilePhoneFieldName": "Mobile Phone",
"nameFieldName": "First Name",
"uniqueIdFieldName": "Employee ID",
"asyncJobId": "e4624d80-bb7f-449a-b53f-f490081311df",
"createdAt": "2020-10-16T20:20:40.631Z",
"membersUpdatedAt": "2020-10-16T20:20:45.123Z",
"updatedAt": "2020-10-16T20:20:40.725Z"
}
]
}

Common Errors

Provide an invalid API Token key

Delete an audience import

Delete an audience import

DELETE /public-api/audience-import/:id

Purpose: Delete an audience import that is no longer useful or used by any audience.

Request headers

Accept REQUIRED	application/json
X-GSCC-Api-Key REQUIRED	This API Token key should be previously generated.

Query Parameters

TIP:

TIP: Make sure provided ID is correct.

id REQUIRED

ID of audience import

Parameters

No parameters

Example request with curl

curl --location --request DELETE 'https://api.guidespark.com/public-api/audience-imports/13b2eaf3-48c2-444b-ae0e-a1950a891eaf' \
--header 'X-GSCC-Api-Key: mKGBXn_H8Qf5MKWVrewesw'

Returns: An empty response with response code 204. Otherwise, this call returns an error, such as the audience import is currently being used by one or more audiences.

Example response

204

Common Errors

• Provide an invalid API Token key
• Provide an invalid audience import ID
• Provide a valid audience import ID but it is currently being used by one or more audiences

Audience Import Async Jobs

Context

Once an audience import object has been created/updated, there is an asynchronous job in charge of importing every row in the csv file that was uploaded. This process can take a while depending on the number of employees to be imported.

In order to track the progress of this asynchronous job, there is a handy endpoint called Status that provides job’s status and progress percentage during import process. In case there are some errors during importing process, the detail of those errors will be available by calling the endpoints Failures.

Example

1. A new Audience Import object was created by calling CXI Public API
2. The response from the creation will have the Id of the asynchronous job ‘asyncJobId’ that will import the CSV file
3. Every certain time (i.e. 30 seconds) Status endpoint is being called to verify status and percentage progress from import process.
4. The response from Status call will include the status till the completion or failure from import process.
5. An async import job is considered successful if status is ‘completed’ and percentage progress is equals to 100.
   • This indicates the audience import is ready to be used to create an Audience or in the case of an update that all audiences based on this audience import will be updated too.
6. An async import job will be considered failed if the status is ‘failed’.
   • This indicates the audience import has some errors in which case the Failures endpoint should be called to have a list of failed rows and a descriptive message for each error.
   • If there are one or more errors the goal will be to fix all errors and try again.

Audience Import Async Job

This is an object representing an asynchronous job created during the creation/update of an audience import. You can retrieve the status of an audience import async job, as well as a list of failures in case there were some errors during the importing process.

https://api.guidespark.com/public-api/audience-imports/async-jobs

The audience import async job object

Attributes

Element	Description
id (uuid)	Unique identifier for the audience import async job object.
audienceImportId (uuid)	ID of audience import the async job is associated with.
fileName (string)	A filename for the csv file.
status (string)	Current audience import async job status. One of pending, in_progress, completed, or failed.
progressPercentage (integer)	Number that indicates percentage of progress from import process
totalNumOfRows (integer)	Number that indicates the total of lines in the imported csv file
numOfRowsProcessed (integer)	Number of rows that were successfully imported from the csv file
numOfRowsFailed (integer)	Number or rows that failed during import process from the csv file
errorMessages (array of hashes)	List of errors that appeared during import process

Endpoints

GET  /public-api/audience-imports/async-jobs/:async_job_id/status
GET  /public-api/audience-imports/async-jobs/:async_job_id/failures

Retrieve status from an audience import async job

Retrieves the audience import async job. You only need to supply the async job ID that was returned upon audience import creation/update or by retrieving current information from an audience import.

GET /public-api/audience-imports/async-jobs/:async_job_id/status

Purpose: Retrieve information from an audience import async job to verify information related to the import process. This is helpful to continuously verify the progress from an import process.

Request headers

Accept REQUIRED	application/json
X-GSCC-Api-Key REQUIRED	This API Token key should be previously generated.

Query Parameters

TIP: Make sure the provided ID is correct.

asyncJobId REQUIRED

ID of audience import async job

Example request with curl

curl --location --request GET 'https://api.guidespark.com/public-api/audience-imports/async-jobs/51aace83-926f-4817-bc86-62d6074c95ef/status' \
--header 'X-GSCC-Api-Key: mKGBXn_H8Qf5MKWVrewesw'

Returns: A basic version of an audience import async object if a valid audience import async job ID was provided. Returns an error otherwise.

Example response

{
"data": {
"id": "51aace83-926f-4817-bc86-62d6074c95ef",
"audienceImportId": "13b2eaf3-48c2-444b-ae0e-a1950a891eaf",
"fileName": "EmployeesList.csv",
"progressPercentage": 20,
"status": "in_progress"
}
}

Common Errors

• Provide an invalid API Token key
• Provide an invalid audience import async job ID

Retrieve failures from an audience import async job

Retrieves all details from an audience import async job including errors if any. You only need to supply the async job ID that was returned upon audience import creation/update or by retrieving current information from an audience import.

GET /public-api/audience-imports/async-jobs/:async_job_id/failures

Purpose: Retrieve information from an audience import async job to verify all information related to import process including a list of errors if any.

Request headers

Accept REQUIRED	application/json
X-GSCC-Api-Key REQUIRED	This API Token key should be previously generated.

Query Parameters

TIP: Make sure the provided ID is correct.

asyncJobId REQUIRED

ID of audience import async job

Example request with curl

curl --location --request GET 'https://api.guidespark.com/public-api/audience-imports/async-jobs/da4f1ca6-5ac9-482c-af9c-736723dac4f0/failures' 
--header 'X-GSCC-Api-Key: mKGBXn_H8Qf5MKWVrewesw'

Returns: An audience import async object with all details from import process if a valid audience import async job ID was provided. Returns an error otherwise.

Example response

{
"data": {
"id": "da4f1ca6-5ac9-482c-af9c-736723dac4f0",
"audienceImportId": "14bc5c8b-fe6d-4c06-8d30-d7b78e9a3a7b",
"fileName": "EmployeesList2.csv",
"progressPercentage": 98,
"status": "failed",
"totalNumOfRows": 100
"numOfRowsProcessed": 98,
"numOfRowsFailed": 2,
"errorMessages": [
{ "line": 20, "error": "Missing unique ID value"},
{ "line": 31, "error": "Missing unique ID value"}
]
}
}

Common Errors

• Provide an invalid API Token key
• Provide an invalid audience import async job ID

FAQ

What is an audience import in CXI?

An audience import is an object that represents a CSV file uploaded to CXI containing employee data. It is used to import employees’ information as Audience Members, which can then be used to create targeted audiences for communication campaigns.

How can I track the progress of an audience import?

You can track the progress of an audience import by using the Status endpoint of the Audience Import Async Jobs API. This endpoint provides information on the job’s status and progress percentage during the import process. You should call this endpoint periodically (e.g., every 30 seconds) to check the import status.

What should I do if there are errors during the audience import process?

If errors occur during the import process, you can use the Failures endpoint of the Audience Import Async Jobs API to retrieve detailed information about the failed rows and error messages. Once you have this information, you should fix the errors in your CSV file and attempt the import again.