Query Bulk Processing Requests

The Query Bulk Processing Requests API endpoint lets you programmatically retrieve the status of bulk processing requests for golden records, including end-dating and purging records, as well as sending update requests to target sources. The API endpoint returns request data for a universe (deployed model). The data aligns with information you can access in the user interface on the Reporting > Bulk Processing Requests screen.

Basic authentication

To perform this operation using Basic auth, send an HTTP POST request to:

https://<base URL>/mdm/universe/<universeId>/bulk/query

JWT authentication

To perform this operation using JSON Web Token (JWT) auth, send an HTTP POST request to:

https://<base URL>/mdm/universe/<universeId>/bulk/query?repositoryId=<repository ID>

You must have the following MDM privileges:

MDM - Source Management

Path parameters

universeID
ID of the universe (deployed model). String. Required.

Query parameters

repositoryId
ID of the repository. Case sensitive. Required with JWT authentication only. You can obtain the repository ID from the URL after navigating to the repository in the user interface.

Request parameters

offsetToken
Add the offset token value from the previous page of results to retrieve the next page of results. String. Optional.

limit
Indicates the maximum number of results to include in a page. Boomi DataHub enforces a maximum of 200 requests per page regardless of the limit value. Integer. Optional.

Filter parameters

Wrap the following query filter parameters in the <filter> tag.

type - Filters by request type. String. Optional. Values are:
- END_DATE - request to end-date a golden record
- PURGE - request to permanently delete an end-dated golden record
- SEND_UPDATES - request to send a record update to a target source
status - filters by request status. String. Optional. Values are:
- ALL - all requests available
- PROCESSING - requests in progress
- ERRORED - requests that completed with errors or terminated as a result of the occurrence of 500 errors
- SUCCESSFUL - requests completed without errors
- SUBMITTED - requests that have been receive but have not yet begun processing
- RETRIED - requests for SEND_UPDATES type where the Retry action was applied in the UI
- CANCELED - requests where the Cancel action was applied in the UI
sourceId - filters by a specific target source ID. Applies only to SEND_UPDATES requests. String. Optional.
startTime - filter by date and time the request was submitted for processing. Datetime. Optional. This tag wraps the to and from tag.
- from: The start datetime for filtering requests. Format is yyyy-MM-dd'T'HH:mm:ss'Z'. Value can be an empty string.
- to: The end datetime for filtering requests. Format is yyyy-MM-dd'T'HH:mm:ss'Z'. Value can be an empty string.
  
  If startTimeRelative filter is specified, it overrides this filter.
startTimeRelative - filters by a request processing start time frame relative to the current date and time. String. Optional. Values are:
- PAST_HOUR
- PAST_24_HOURS
- PAST_WEEK
endTime - filter by date and time the request finished processing. Datetime. Optional. This tag wraps the to and from tag.
- from: The start datetime for filtering requests. Format is yyyy-MM-dd'T'HH:mm:ss'Z'. Value can be an empty string.
- to: The end datetime for filtering requests. Format is yyyy-MM-dd'T'HH:mm:ss'Z'. Value can be an empty string.
  
  If endTimeRelative filter is specified, it overrides this filter.
endTimeRelative - filters by a request processing end time frame relative to the current date and time. String. Optional. Values are:
- PAST_HOUR
- PAST_24_HOURS
- PAST_WEEK

Request body examples

<BulkProcessingQueryRequest limit="2">
  <filter>
    <type>SEND_UPDATES</type>
       <startTime>
            <from>2025-02-17T15:07:00Z</from>
            <to>2025-02-17T15:07:59Z</to>
        </startTime>
  </filter>
</BulkProcessingQueryRequest>

<BulkProcessingQueryRequest offsetToken="Mg==">
    <filter>
        <type>SEND_UPDATES</type>
        <status>SUCCESSFUL</status>
    </filter>
</BulkProcessingQueryRequest>

Response examples

200 (OK) The body contains the XML representation of the query results. It returns a maximum of 200 results per request unless the limit parameter for a given request specifies a lower maximum number of results.

Each <request> element represents a bulk processing request. It has the below elements:
id - Unique ID for the bulk processing request
type - Bulk Processing Request type. Possible values END_DATE, PURGE, SEND_UPDATES
status - status of the bulk processing request. Possible values SUBMITTED, PROCESSING, SUCCESSFUL, ERRORED, CANCELED, RETRIED
sourceId - source’s user-specified unique ID (returned only for SEND_UPDATES type)
recordsTotal - Total records processed in the request
recordsSuccess - Total records processed successfully in the request
recordsError - Total records that errored out during processing
completePercentage - Completion percentage of the request (will be less than 100 if the request is still processing)
startTime - Start time of the bulk processing request
endTime - End time of the bulk processing request (will be null for requests that are still processing)
timeElapsed - Time elapsed in seconds

Sample response body:

<BulkProcessingQueryResponse resultCount="5" totalCount="5">
	<request>
		<id>176</id>
		<type>PURGE</type>
		<status>SUCCESSFUL</status>
		<recordsTotal>13</recordsTotal>
		<recordsSuccess>13</recordsSuccess>
		<recordsError>0</recordsError>
		<completePercentage>100</completePercentage>
		<startTime>2025-02-17T15:12:00Z</startTime>
		<endTime>2025-02-17T15:12:00Z</endTime>
		<timeElapsed>0</timeElapsed>
	</request>
	<request>
		<id>175</id>
		<type>END_DATE</type>
		<status>SUCCESSFUL</status>
		<recordsTotal>13</recordsTotal>
		<recordsSuccess>13</recordsSuccess>
		<recordsError>0</recordsError>
		<completePercentage>100</completePercentage>
		<startTime>2025-02-17T15:11:28Z</startTime>
		<endTime>2025-02-17T15:11:33Z</endTime>
		<timeElapsed>5</timeElapsed>
	</request>
	<request>
		<id>174</id>
		<type>SEND_UPDATES</type>
		<sourceId>sap</sourceId>
		<status>SUCCESSFUL</status>
		<recordsTotal>11289</recordsTotal>
		<recordsSuccess>11289</recordsSuccess>
		<recordsError>0</recordsError>
		<completePercentage>100</completePercentage>
		<startTime>2025-02-17T15:07:40Z</startTime>
		<endTime>2025-02-17T15:08:38Z</endTime>
		<timeElapsed>58</timeElapsed>
	</request>
	<request>
		<id>173</id>
		<type>SEND_UPDATES</type>
		<sourceId>sf</sourceId>
		<status>SUCCESSFUL</status>
		<recordsTotal>11289</recordsTotal>
		<recordsSuccess>11289</recordsSuccess>
		<recordsError>0</recordsError>
		<completePercentage>100</completePercentage>
		<startTime>2025-02-17T15:07:40Z</startTime>
		<endTime>2025-02-17T15:08:38Z</endTime>
		<timeElapsed>58</timeElapsed>
	</request>
	<request>
		<id>172</id>
		<type>SEND_UPDATES</type>
		<sourceId>ns</sourceId>
		<status>SUCCESSFUL</status>
		<recordsTotal>11289</recordsTotal>
		<recordsSuccess>11289</recordsSuccess>
		<recordsError>0</recordsError>
		<completePercentage>100</completePercentage>
		<startTime>2025-02-17T15:07:40Z</startTime>
		<endTime>2025-02-17T15:08:43Z</endTime>
		<timeElapsed>63</timeElapsed>
	</request>
</BulkProcessingQueryResponse>

204 (No Content) There are no requests that match the filter criteria. No response body returned.
400 (Bad Request) The universeID parameter value contains only space characters. Sample response body:

  <error>
    <message>The given universe id is blank.</message>
  </error>

400 (Bad Request) The sourceId filter specified for request types other than SEND_UPDATES. Sample response body:

<error>
    <message>Invalid request type PURGE for BulkProcessingQueryRequest with sourceId filter</message>
</error>

400 (Bad Request) Invalid request structure. Sample response body:

<error>
    <message>Unable to read message body. Please make sure the XML structure is correct. </message>
</error>

401 (Invalid Credentials) JWT auth token is expired. Sample response body:

<error>
<message>Problem accessing /mdm/universes. Reason: Invalid credentials</message>
</error>

403 (You do not have permissions to access this resource) User does not have the required MDM privilege to perform the action. Applicable to JWT auth only. Sample response body:

<error>
<message>You do not have permissions to access this resource.</message>
</error>