Jobs API

Use Acoustic Exchange jobs API to manage exchange of audience data through Exchange.

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 Exchange 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 Exchange 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 Exchange 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.

Response

Acoustic Exchange 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,
}]

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 Acoustic Exchange. 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 Acoustic Exchange 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>

Response

Acoustic Exchange 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
}]

POST /v1/jobs/{jobId}/data

Upload audience segment data to a pending SEGMENT_EXPORT job in Acoustic Exchange.

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 Exchange and is in WAITING_TO_RECEIVE_DATA state. In Exchange, 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, Exchange 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 Acoustic Exchange.

Request

Direct the API call to the base URL that is assigned to your Acoustic Exchange 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,[email protected],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

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

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

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

Delete audience data files from Exchange 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 Exchange to a destination endpoint. Some files that did not download successfully might remain on Exchange. 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 Exchange can call this API to clean up any files that might remain on Exchange after downloading the audience data from Acoustic Exchange.

Request

Direct the API call to the base URL that is assigned to your Exchange 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>

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

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

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

Pull audience data from Acoustic Exchange to a destination endpoint.

About this API

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

The call takes jobId and fileName as URL parameters. Specify the .CSV file in Exchange that contains the audience data that is ready to download to the destination endpoint. Specify the ID job that is created in Exchange 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 Exchange. 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 Exchangeaccount.

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>

Response

Exchange public APIs return standard HTTP 1.1 response codes.

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

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 Exchange 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 Exchange. Typically, you call this API after getting segment files from Exchange 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 Exchange to the destination endpoint.

Request

Direct the API call to the base URL that is assigned to your Exchange 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

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

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

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 Acoustic Exchange. The API call changes the job status on the 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 Exchange 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”: “”}’
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

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

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

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 Exchange. 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 Exchange 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>

Response

Acoustic Exchange 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
  }
]

DELETE /v1/scheduledjobs/{scheduledjobid}

You can use this API to delete scheduled jobs in Acoustic Exchange.

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 Exchange. 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 Exchange 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>

Response

Exchange public APIs return standard HTTP 1.1 response codes.

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