Jobs API

Use UBX jobs API to manage exchange of audience data through UBX.

GET /v1/jobs/{jobCategory}

Get a list of one or more waiting jobs, which are identified by category, endpoint ID, or status. This API is used to get jobs that process audience data.

About this API

Call this API to return a list of jobs that are available in UBX by specifying the job category. For example, SEGMENT_EXPORT. You can further refine the request by specifying an endpoint and job status.

Note: To make this call successfully, you must have access authorization across all endpoints that are registered for the user account.

Request

Direct the API call to the base URL that is assigned to your UBX account.

You can specify SEGMENT_EXPORT, IDENTITY_IMPORT, or SEGMENT_POPULATE_DB as the job category path parameter . This call also accepts various optional query parameters that you can include to filter the result of the call. You can specify multiple URL parameters in the call. Use the character & to separate query parameters.

For the authorization bearer, you can provide any account-level or endpoint level authentication key that is associated with your UBX account, unless you specify a particular endpoint. If you specify an endpoint, you must use the account-level authentication key or the specific authentication key signed to the endpoint.

SEGMENT_EXPORT example request (as a curl command):

curl -v 
  -X GET 
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  <base URL>/v1/jobs/SEGMENT_EXPORT?
  endpointId=<endpoint ID>&status=<status>
   
  For example, calling 
  <base URL>/v1/jobs/SEGMENT_EXPORT?endpointId=85&
  extraFields=true&
  status=WAITING_TO_RECIEVE_DATA 

  returns all segment export jobs that are waiting for endpoint 85 to upload 
  audience data.
Path parameters: Job Category (required) Description
SEGMENT_EXPORT Returns a list of jobs that were created to share audience data from a source endpoint to a
destination endpoint and, if specified, upload audience data to the UBX identity store.
IDENTITY_IMPORT Returns a list of jobs that were created to upload audience data to the UBX identity store only.
SEGMENT_POPULATE_DB Returns a list and status of jobs that were created to update audience data that is stored in UBX databases.
Query parameters: Endpoint ID (optional) Description
endpointID Specify one endpoint that is registered to the account that is associated with the
authentication key that is specified as the Authorization Bearer.
Query parameters: Status (optional) Description
WAITING_TO_RECIEVE_DATA UBX is waiting for a segment source to upload audience data. The endpoint must be designated
a push segment source.
SCHEDULED The job is scheduled.
PENDING The job is pending.
RUNNING The job is running.
COMPLETE The job is finished.
ERROR The job is not running because of an error.
CANCELLED The job is canceled.
NOTFOUND The job was not found with the search criteria that were entered.
READY_FOR_DOWNLOAD UBX has audience data that is ready to be downloaded to an endpoint. The endpoint must be designated a pull segment destination.
Additional query parameters Description
includeProducerSegmentIDString If the segment source supports a string segment ID, pass this parameter to return producerSegmentIDString.
extraFields If the this parameter is set to true, the call returns additional schedule information, such
as started, ended, and scheduleDetails. If set to false, the additional information is not included.

Response

UBX public APIs return standard HTTP 1.1 response codes.

GET
/v1/jobs/SEGMENT_EXPORT?endpointId=85&extraFields=true&status=WAITING_TO_RECIEVE_DATA

provides responses as follows.

Example response (values are presented for example only):

[{
   "jobCategory":"SEGMENT_EXPORT", 
   "jobId":1347,
   "scheduledJobId":1234,
   "status":"WAITING_TO_RECIEVE_DATA",
   "jobName":"EXPORT_SEGMENT",
   "accountId":2,
   "producerSegmentIDString":null,
   "segmentDataFiles":null,
   "segmentDataFormat":null,
   "destinationSegmentID":null, 
   "destinationSegmentName":"myDestSegName",
   "destinationSegmentDescription":null,
   "destinationEndpointID":7,
   "exportCategory":"mycat2",
   "producerEndpointID":85,
   "producerSegmentIDString":null,
   "producerSegmentID":45311,
   "updateIdentities":false,
   "sourceIdentifiers":null,
   "destinationIdentifier":null
   "attributeMappings":{},
   "identityMappings":{
     "Email":"workEmail"},
   "started":1471005788694,
   "ended":1471007416451,
   "scheduleDetails":{
     "runNow":true|false,
     "runRepeat":true|false,
     "daysOfWeek":<day of the week>,
     "daysOfMonth":<day of the month>,
     "monthsOfYear":<months of the year>,
     "year":<the year>,
     "startHour":"<the hour to start>",
     "startMinute":"<the minute to start>",
     "startSecond":"<the second to start>",
     "startDate":"<the start date>",
     "endDate":<the end date>,
     "timeSliceStartDate":<date>,
     "timeSliceEndDate":<date>},
   "translatedRecordCount":27397,
   "sourceRecordCount":27397,
   "destinationRecordCount":27397,
}]
JSON Output
jobCategory

SEGMENT_EXPORT |IDENTITY_IMPORT

jobId The job ID
scheduledJobId The ID of the scheduled job.
status Current status of the job at the time of the API call.
jobName The job name.
accountId The account ID for the UBX user account that owns the endpoints for which the jobs have been created.
segmentDataFiles Names of the .csv files that contain the audience data.
segmentDataFormat text/csv (default)
destinationSegmentID ID of the segment that is downloaded to the destination endpoint.
destinationSegmentName Name of a segment that is downloaded to the destination endpoint.
destinationSegmentDescription Description of a segment that is downloaded to the destination endpoint.
destinationEndpointID ID of an endpoint that accepts the downloaded segment.
exportCategory The export category.
producerEndpointID ID of an endpoint that produces audience data and uploads it to UBX.
producerSegmentID ID for a segment that is uploaded to UBX.
producerSegmentIDString ID string for segments that are uploaded to UBX
updateIdentities As defined by calling POST /v1/jobs/segmentExport or POST
/v1/jobs/identityImport
.
sourceIdentifiers As defined by calling POST /v1/jobs/segmentExport or POST
/v1/jobs/identityImport
.
destinationIdentifier As defined by calling POST /v1/jobs/segmentExport or POST
/v1/jobs/identityImport
.
attributeMappings As defined by calling POST /v1/jobs/segmentExport or POST
/v1/jobs/identityImport
.
identityMappings As defined by calling POST /v1/jobs/segmentExport or POST
/v1/jobs/identityImport
.
started Indicates start time of the job.
ended Indicates the end time of the job. If the value is null, the job is ongoing.
scheduleDetails The schedule details for the job. The schedule details are defined by calling POST /v1/jobs/segmentExport or POST /v1/jobs/identityImport.
translatedRecordCount The number of identities that UBX matched to the audience destination.
sourceRecordCount The number of identities that UBX receives from the audience source.
destinationRecordCount The number of identities that UBX sends to the audience destination.

GET /v1/jobs/{jobCategory}/{jobId}

Get a specific job, identified by job category and job ID.

About this API

Call this API to return a specific job that has been created in UBX. You must specify the job category and the job ID for the job that you want to get.

Request

Direct the API call to the base URL that is assigned to your UBX account.

The call accepts job category and job ID as URL parameters.

You can use either the account-level or endpoint-level authentication key as the authorization bearer in the API call. If you specify an endpoint-level authentication key, the results are filtered by endpoint.

Example request (as a curl command):

curl -v 
  -X GET 
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  <base URL>/v1/jobs/<jobCategory>/<jobId>
Query parameter Use Description
jobCategory Required

Must be one of the following:

  • IDENTITY_IMPORT
  • SEGMENT_EXPORT
  • SEGMENT_POPULATE_DB
jobId Required The job ID of the job that you want to get.

Response

UBX public APIs return standard HTTP 1.1 response codes.

GET /v1/jobs/{jobCategory}/{jobId} provides descriptive information for the job that you specified, as follows.

Example response (values are presented for example only):

[{
   "jobCategory":"SEGMENT_EXPORT",
   "jobId":1347,
   "scheduledJobId":null,
   "status":"WAITING_TO_RECIEVE_DATA",
   "jobCategory":"SEGMENT_EXPORT",
   "jobName":"EXPORT_SEGMENT",
   "accountId":2,
   "subStatus":"EXPORT_SEGMENT",
   "errorDetails":null,
   "segmentDataFiles":null,
   "segmentDataFormat":null,
   "destinationSegmentID":null,
   "destinationSegmentName":"64123-abc-020",
   "destinationSegmentDescription":"upload",
   "destinationEndpointID":7,
   "exportCategory":"abc",
   "producerEndpointID":85,
   "producerSegmentIDString":null,
   "producerSegmentID":45311,
   "attributeMappings":{
   },
   "identityMappings":{
      "Email":"EMAIL_SHA256"
   },
   "shareAction":null,
   "updateIdentities":false,
   "sourceIdentifiers":null,
   "destinationIdentifier":null,
   "started":1485977027195,
   "ended":null,
   "scheduleDetails":null,
   "translatedRecordCount":null,
   "sourceRecordCount":null,
   "destinationRecordCount":null
}]
JSON Output
jobCategory

SEGMENT_EXPORT |IDENTITY_IMPORT

jobId The job ID.
scheduledJobId The ID of the scheduled job.
status Status of the job at the time of the API call.
jobName The job name.
accountId The account ID for the UBX user account that owns the endpoints for which the jobs have been created.
segmentDataFiles Names of the .csv files that contain the audience data.
segmentDataFormat text/csv (default)
destinationSegmentID ID of the segment that is downloaded to the destination endpoint.
destinationSegmentName Name of a segment that is downloaded to the destination endpoint.
destinationSegmentDescription Description of a segment that is downloaded to the destination endpoint.
destinationEndpointID ID of an endpoint that accepts the downloaded segment.
exportCategory The export category.
producerEndpointID ID of an endpoint that produces audience data and uploads it to UBX.
producerSegmentID ID for a segment that is uploaded to UBX.
producerSegmentIDString ID string for segments that are uploaded to UBX
attributeMappings As defined by calling POST /v1/jobs/segmentExport
identityMappings As defined by calling POST /v1/jobs/segmentExport
shareAction As defined by calling POST /v1/jobs/segmentExport
updateIdentities As defined by calling POST /v1/jobs/segmentExport
sourceIdentifiers As defined by calling POST /v1/jobs/segmentExport
destinationIdentifier As defined by calling POST /v1/jobs/segmentExport
started The time that the job started.
ended The time that the job ended. If the value is null, the job is ongoing.
scheduleDetails If the job is scheduled to repeat, start, or end at a specific time, details of that schedule
appear in this field.
translatedRecordCount If updateIdentities is set to true, then this field shows the number of identities that UBX matched to the audience destination.
sourceRecordCount If updateIdentities is set to true, then this field shows the number of identities that UBX receives from the audience source.
destinationRecordCount If updateIdentities is set to true, then this field shows the number of identities that UBX sends to the audience destination.

POST /v1/jobs/{jobId}/data

Upload audience segment data to a pending SEGMENT_EXPORT job in UBX.

About this API

Call this API to upload audience data from a push type segment producer endpoint to a SEGMENT_EXPORT job that is created in UBX and is in WAITING_TO_RECEIVE_DATA state. In UBX, audience data is synonymous with comma-separated value data.

When you call POST /v1/jobs/segmentExport from an endpoint that is configured as a push segment producer, UBX automatically creates a SEGMENT_EXPORT job and puts the job into WAITING_TO_RECEIVE_DATA state.

You can call GET /v1/jobs/SEGMENT_EXPORT?status=WAITING_TO_RECIEVE_DATA to find the waiting job and then call POST /v1/jobs/{jobId}/data to upload audience segment data to the job in UBX.

Request

Direct the API call to the base URL that is assigned to your UBX account.

The request requires that you provide a job ID as a URL parameter. For example, call POST /v1/jobs/segmentExport or GET /v1/jobs to return a job ID.

You can use either the account-level or endpoint-level authentication key as the authorization bearer in the API call.

Example request (as a curl command):

curl -v 
  -X POST 
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  -d "email,firstName,lastNamenjsmith@example.com,jane,smith"
<base URL>/v1/jobs/<jobID>/data

In this request, the value for -d is a list of comma-separated values, or .csv. The .csv is uploaded to the SEGMENT_EXPORT job as audience segment data.

Response

UBX public APIs return standard HTTP 1.1 response codes.

POST /v1/jobs/{jobId}/data provides responses as follows.

Code Description

200 – 299

Success. UBX returns the job ID of the segment export job that ran to upload the audience data to UBX.

400 – 499

There is a problem with the API request. Examine the request for errors.

500 – 599

System error. Contact IBM for assistance.

DELETE/v1/jobs/{jobId}/segmentDataFiles/{fileName}

Delete audience data files from UBX after downloading the data to pull-type audience
destination endpoint.

Before you begin

Call GET /v1/jobs/{jobId}/segmentDataFiles/{fileName} to download audience data from UBX to a destination endpoint. Some files that did not download successfully might remain on UBX. To maintain efficient operation, you can remove the remaining files by calling DELETE/v1/jobs/{jobId}/segmentDataFiles/{fileName}

About this API

Pull-type endpoints that download audience data from UBX can call this API to clean up any files that might remain on UBX after downloading the audience data from UBX.

Request

Direct the API call to the base URL that is assigned to your UBX account.

The call accepts job category and job ID as URL parameters.

You can use either the account-level authentication key or the endpoint-level authentication key of the destination endpoint as the authorization bearer in the API call.

Example request (as a curl command):

curl -v 
    -X DELETE
    -H "Authorization: Bearer 1234-abcd-5678-efgh" 
    <base URL>/v1/jobs/<jobId>/segmentDateFiles/
    <file name>
Query parameters Description
jobId The ID of the job that was created on UBX to download the audience data.
file name Name of the .csv file that contained the audience data that you downloaded from UBX to the destination endpoint.

Response

UBX public APIs return standard HTTP 1.1 response codes.

DELETE /v1/jobs/{jobId}/segmentDataFiles/{fileName} provides responses as
follows.

Code Description

200 – 299

Success. The files are deleted successfully from UBX..

400 – 499

There is a problem with the API request. Examine the request for errors.

For example:

  • 401: Not authenticated
  • 403: Not authorized
  • 404: The job or file is unknown

500 – 599

System error. Contact IBM for assistance.

GET /v1/jobs/{jobId}/segmentDataFiles/{fileName}

Pull audience data from UBX to a destination endpoint.

About this API

Endpoints that consume audience data can call this API to download audience data from UBX as a stream of comma-separated data to the destination endpoint. The endpoint must be registered with UBX as a PULL type destination endpoint.

The call takes jobId and fileName as URL parameters. Specify the .CSV file in UBX that contains the audience data that is ready to download to the destination endpoint. Specify the ID job that is created in UBX to download the audience data
in the file. The status of the job must be READY_FOR_DOWNLOAD.

When you download a large segment of audience data, the data can sometimes be broken up into multiple files. When this happens, there is header for each file.

After completing the download of audience data, delete the file on UBX. You can delete the file by calling DELETE/v1/jobs/{jobId}/segmentDataFiles/{fileName} or set the job status to complete by calling PUT /v1/jobs/{jobid}/status/complete. Setting the job status to complete automatically deletes any remaining files.

Request

Direct the API call to the base URL that is assigned to your UBX account.

The call accepts jobId and the file name as URL parameters. You can find the file name in the response to GET /v1/jobs or GET /v1/jobs/{jobCategory}/{jobId}.

To specify the user account, provide the authentication key for the account as the authorization bearer in the API call.

Example request (as a curl command):

curl -v 
  -X GET
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  <base URL>/v1/jobs/<jobId>/segmentDataFiles/
  <file name>
Query parameters Description
jobId The ID of the job that was created on UBX to download the audience data.
file name Name of the .segment file that contained the udience data that you download from UBX to the destination endpoint.

Response

UBX public APIs return standard HTTP 1.1 response codes.

GET /v1/jobs/{jobId}/segmentDataFiles/{fileName} provides responses as follows.

Code Description

200 – 299

Success. UBX downloads a stream of comma-separated audience data to the destination endpoint.

400 – 499

There is a problem with the API request. Examine the request for errors.

For example:

  • 401: Not authenticated
  • 403: Not authorized
  • 404: The job or file is unknown

500 – 599

System error. Contact IBM for assistance.

PUT /v1/jobs/{jobid}/status/complete

Mark a job as complete and delete remaining files.

About this API

Call this API after pulling audience data from UBX to mark the download job as complete. You must include the job ID for the job in the API request.

This API is used by endpoints that pull audience data from UBX. Typically, you call this API after getting segment files from UBX by calling GET /v1/segmentfiles/{fileName}.

When the job finishes, this API deletes any audience data files that were not deleted when they were downloaded from UBX to the destination endpoint.

Request

Direct the API call to the base URL that is assigned to your UBX account.

The call accepts jobId as a URL parameter. Specify the job ID of the job that ran to download audience data to the destination endpoint.

You can use either the account-level or endpoint-level authentication key as the authorization bearer in the API call.

To specify the user account, provide the authentication key for the account as the authorization bearer in the API call. Use the account-level or endpoint-level authentication key.

Example request (as a curl command):

curl -v 
  -X PUT
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  <base URL>/v1/jobs/<jobId>/status/complete

Response

UBX public APIs return standard HTTP 1.1 response codes.

PUT /v1/jobs/{jobid}/status/complete provides responses as follows.

Code Description

200 – 299

True: The job is marked complete and files that were not downloaded are
deleted from UBX.

False: The job is not marked complete or all files are not deleted.

403

Not authorized. There might be a problem with the authentication key.

500 – 599

System error. Contact IBM for assistance.

PUT /v1/jobs/{jobid}/status/fail

Update job status from WAITING_TO_RECIEVE_DATA to ERROR.

About this API

Call this API when you encounter a problem pushing audience data to UBX. The API call changes the job status on the UBX Audiences tab from Waiting to receive data to Error to indicate to the user that a problem has occurred. You must include the job ID for the job in the API request.

Request

Direct the API call to the base URL that is assigned to your UBX account.

The call accepts jobId as a URL parameter. Specify the job ID of the job that ran to download audience data to the destination endpoint.

You can use either the account-level or endpoint-level authentication key as the authorization bearer in the API call.

Note: You must include the JSON object ‘{“errorMessage”: “<error message text>”}’
in the body of the call, and specify the error message. The call fails if you do not.

Example request (as a curl command):

curl -v 
    -X PUT
    -H "Authorization: Bearer 1234-abcd-5678-efgh" 
    -d '{"errorMessage": "<error message text>"}'     
    <base URL>/v1/jobs/<jobId>/status/fail

Response

UBX public APIs return standard HTTP 1.1 response codes.

PUT /v1/jobs/{jobid}/status/fail provides responses as follows.

Code Description

200 – 299

True: The job is updated and marked failed.

False: The job is not marked failed.

403

Not authorized. There might be a problem with the authentication key.

500 – 599

System error. Contact IBM for assistance.

GET /v1/scheduledjobs/{jobcategory}

You can use this API to get scheduled jobs as identified by job category.

About this API

Call this API to return a list scheduled jobs that were created in UBX. You must first specify the job category for the jobs that you want to return.

This API can be useful if you need a list of all scheduled jobs in a category and their respective job IDs. For example, if you want to delete a scheduled job, you can use this API to get the job ID of the job that you want to delete.

Request

Direct the API call to the base URL that is assigned to your UBX account.

The call accepts job category as URL parameters.

You can use either the account-level or endpoint-level authentication key as the authorization bearer in the API call. If you specify an endpoint-level authentication key, the results are filtered by endpoint.

Example request (as a curl command):

curl -v 
-X GET 
-H "Authorization: Bearer 1234-abcd-5678-efgh" 
<base URL>/v1/scheduledjobs/<category>?
endpointId=<endpoint ID>
Query parameter Use Description
jobCategory Required

Must be SEGMENT_EXPORT

endpointId Optional The endpoint ID of the job that you want to get.

Response

UBX public APIs return standard HTTP 1.1 response codes.

GET /v1/scheduledjobs/{jobcategory} provides descriptive information for the job that you specified, as follows.

Example response (values are presented for example only):

[
  {
    "jobId": 301,
    "state": "SCHEDULED",
    "jobCategory": "SEGMENT_EXPORT",
    "jobName": "EXPORT_SEGMENT",
    "accountId": 2,
    "active": 1,
    "errorDetails": null
  },
  {
    "jobId": 1044,
    "state": "SCHEDULED",
    "jobCategory": "SEGMENT_EXPORT",
    "jobName": "EXPORT_SEGMENT",
    "accountId": 2,
    "active": 1,
    "errorDetails": null
  }
]
JSON Output
jobId The job ID.
state Current state of the job at the time of the API call.
jobCategory

SEGMENT_EXPORT

jobName The job name.
accountId The account ID for the UBX user account that owns the endpoints for which the jobs were
created.
active If the scheduled job is active 1 or inactive 2.
errorDetails If an error occurs, its details are listed here.

DELETE /v1/scheduledjobs/{scheduledjobid}

You can use this API to delete scheduled jobs in UBX.

Before you begin

Call GET /v1/scheduledjobs/{jobcategory} to return a list of scheduled jobs and their respective IDs, then select the scheduled jobs to be deleted.

About this API

Call this API to delete scheduled jobs that were created in UBX. You must first specify the job ID for the job that you want to delete.

Request

Direct the API call to the base URL that is assigned to your UBX account.

You can use either the account-level or endpoint-level authentication key as the authorization bearer in the API call. If you specify an endpoint-level authentication key, the results are filtered by endpoint. To use endpoint-level authentication for this API, you must use either the
source or destination endpoint authentication key.

Example request (as a curl command):

curl -v 
-X DELETE 
-H "Authorization: Bearer 1234-abcd-5678-efgh" 
<base URL>/v1/scheduledjobs/<scheduledjobId>
Query parameter Use Description
jobId Required The job ID of the job that you want to delete.

Response

UBX public APIs return standard HTTP 1.1 response codes.

DELETE /v1/scheduledjobs/{scheduledjobid} provides responses as
follows.

Code Description

200 – 299

Success. The scheduled jobs are deleted successfully from UBX..

400 – 499

There is a problem with the API request. Examine the request for errors.

For example:

  • 401: Not authenticated
  • 403: Not authorized
  • 404: The job or file is unknown

500 – 599

System error. Contact IBM for assistance.

Join The Discussion

Your email address will not be published. Required fields are marked *