Skip to main content

Promotions Suite

The Promotions Suite APIs create and update campaign audiences using retail banking member IDs. These APIs support audience list uploads and provide status information while the list is being processed and prepared for use in Promotions Suite.

Note: These endpoints require a V1 OAuth token. See Authentication API documentation for V1 token endpoint details. Requests are scoped by the fiId path parameter.

End-user benefits​

  • Upload audience lists through the API instead of using the Promotions Suite UI.
  • Monitor processing progress using a jobId.
  • Use a new audience list for campaign targeting as soon as the job reaches Uploading. Members become eligible for the campaign as they are processed.

Integration capabilities​

  • Create audience lists and track their processing status through the API.
  • Monitor upload progress and processing results using a generated jobId.
  • Review job details, including member counts, validation results, and processing timestamps.
  • Access job status information for up to 30 days after processing completes.
  • Handle rate limits when the maximum number of upload jobs are already in progress.

Required headers​

HeaderDescription
AuthorizationBearer {token} (OAuth V1)
di_tidUUID used to trace and correlate requests across services for debugging and logging.

Error codes​

HTTP Status CodeMessage
400User list can't be empty
400User list name can't be empty
400User list name must not be empty
400User list name should not be more than 50 characters
400User list name should not contain special characters
400User list description should not be more than 200 characters
400User list description should not contain special characters
400Malformed request: the uuid {jobId} doesn't have the right format. Please check the uuid and retry.
400No job status found for the given job ID
401There was an authorization error. Check that the correct credentials have been supplied.
404No job found for the given jobId and fiId (empty response body)
429Too many user lists are awaiting processing. Please try again later.
500An unexpected error occurred while handling the request.

Endpoints​

Get User List Upload Job

Retrieves the current status and progress of a user list upload job identified by `jobId`.

Create User List Upload Job

Enqueues a job to upload a named user list to Promotions Suite. The request returns a `jobId`