Audience
The Audience APIs support campaign audience management using CSV files uploaded through SFTP. After a file is uploaded, these APIs are used to register audience list information, monitor processing status, and check whether an error report is available for files that were not processed successfully.
The CSV file must be uploaded to SFTP before calling these APIs. The userlistFileName must
match the uploaded file name and follow the format FI<fiId>_<fileLabel>_<yyyyMMddHHmmss>.csv,
where fiId is a 5-digit institution ID.
End-user benefits
- Create and manage audience lists using files delivered through SFTP.
- Associate uploaded files with a specific audience list and audience update operation.
- Monitor processing status, user counts, and processing results without accessing the source file.
- Access error report information for files that contain invalid records or processing issues.
Integration capabilities
- Register an uploaded audience file by providing a file name, audience list name, operation type, and optional description.
- Retrieve processing details, including job status, user counts, processing messages, and error report availability.
- Access error report information for failed or partially successful file uploads.
- Track file processing status through API responses after metadata is submitted.
- Processing occurs asynchronously. Successful metadata registration returns HTTP 200 with an empty response body.
Scopes
| Scope | Description |
|---|---|
audience:read | Required for Get User List File Details (viewName=fileStatus or fileErrorReport) |
audience:write | Required for Create User List Metadata |
Required headers
| Header | Description |
|---|---|
Authorization | Bearer {token} (OAuth V2) |
transactionId | UUID used to trace and correlate requests across services for debugging and logging. |
Error codes
| Code | Message | HTTP Status Code |
|---|---|---|
| 401 | Invalid JWT | 401 |
| 2001 | Exception occurred while processing the request in the application | 500 |
| 2003 | Invalid header value : {header} | 400 |
| 2005 | Missing header : {header} | 400 |
| 2006 | {header} Cannot be empty or null | 400 |
| 2009 | File Metadata input is incomplete, please provide all mandatory fields [userlistFileName,userlistName,userlistOperation] | 400 |
| 2009 | FileName is not in the required format FI<fiId>filename<yyyyMMddHHmmss>.csv | 400 |
| 2009 | Invalid operation name provided. Please provide one of these valid values [ADD, CREATE, CREATE_OR_REPLACE, CREATE_OR_ADD, REMOVE, REPLACE] | 400 |
| 2009 | Metadata already exists for the filename {userlistFileName} | 400 |
| 2009 | Input request is incomplete, please provide all mandatory fields [userlistFileName,viewName] | 400 |
| 2009 | Input request is incomplete, please provide mandatory field [userlistFileName] | 400 |
| 2009 | Input request is incomplete, please provide mandatory field [viewName] | 400 |
| 2009 | Invalid viewname provided.Please provide one of these valid values [fileErrorReport, fileStatus] | 400 |
| 2009 | No details exist in the system for the given filename. | 400 |
| 2009 | Malformed JSON request | 400 |
| 3000 | Validation Failed | 400 |
Endpoints
Was this page helpful?