Waiting for engine...
Skip to main content

Boomi Data Hub Repository API Reference (1.0.0) - Channels

Toggle Pane
API docs by Redocly

Download OpenAPI Specification: Download

Run In Postman

For more information about Postman collections, forking, and making your first API call, refer to the Working with Boomi APIs on Postman page.

Channels

Integrate real-time updates with external systems. Fetch, acknowledge, and manage channel-based updates exchanged between Data Hub and contributing or consuming systems. Use this API to synchronize mastered data changes across applications.

Fetch Channel Updates

The Fetch Channel Updates operation fetches a batch, if present, in XML format, of up to 200 source record update requests on a specified contributing source's channel from a universe (domain) under the authenticated account.

Additional Information: Note: You can implement requests for this operation in processes using the Boomi Data Hub connector's fetch channel updates operation. You can also implement requests in their standard form using the Boomi Master Data Hub connector, as demonstrated by the sample process Hub: Fetch Channel Updates - Auto, which you can install in your account from the process library in Integration.

For a channel configured to propagate source record update requests that contain entities with all fields from golden records, the entities in fetched requests represent the current states of golden records. This sequence is also the case even for golden records for which multiple updates occurred since the most recently delivered request.

Suppose a channel configured to propagate source record update requests contains entities with only updated fields from golden records. In that case, the fetched requests are accumulations of all field updates since the most recently delivered requests are associated with the golden records.

Suppose deliverable update requests are among the first 201 update requests on the channel. In that case, no further update requests are evaluated for possible delivery in the batch, even if the batch contains less than the number of update requests specified in the limit query parameter (default 200).

Optionally, the operation acknowledges delivery of a previous batch of requests fetched through the same channel.

The operation automatically acknowledges delivery of a batch of requests previously fetched through the same channel if all requests in the batch have in the meantime been manually deleted.

The operation automatically deletes from batches requests in which there are no fields present as a result of the application of field-level delivery exclusions configured for the source. When all records in a batch are deleted in this manner, the resulting empty batch is automatically acknowledged by the next operation.

Multiple Channels: If the source is configured with multiple channels, instead send an HTTP POST request to: /universes/{universeId}/sources/{sourceId}/channels/{channelId}/updates/{updateId}. (Boomi maintains this form for backward compatibility - you cannot configure newly attached sources with multiple channels.)

Security Requirements: You must have one of the following MDM privileges:

Without Advanced Security:

  • MDM - Activity Reporting and MDM - View Data and MDM - Stewardship OR
  • MDM - Activity Reporting and MDM - View Data and MDM - Stewardship Management
Authorizations:
basicAuthbearerAuth
path Parameters
universeId
any
Example: 851a6a64-6a88-4916-a5b7-d6a974d54318

Universe ID. Listed in the Repositories UI URL.

sourceId
any
Example: CRM_SYSTEM

Source ID. The source ID is listed on the Sources page in the user interface.

updateId
any
Example: 3

ID of the channel update to be acknowledged

query Parameters
repositoryId
any

Repository ID. 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.

limit
any
Example: limit=200

Maximum number of source record update requests in the fetched batch. 200 is the maximum meaningful value and the default.

Responses

Response Schema: application/xml
string

Response samples

Content type
application/xml
<batch id="2" fmt="DIFF" src="SF">
      <contact grid="b1fe318c-b80f-44d0-8df0-4b0290c07744" op="UPDATE" ts="04-24-2012T16:42:00.000-0400">
        <id>4</id>
        <name>jeff</name>
      </contact>
      <contact grid="c4d94a09-a181-4259-97c8-bba9f198a89c" op="CREATE" ts="04-24-2012T16:42:37.000-0400">
        <id />
        <name>jason</name>
        <city>east norriton</city>
        <email>jason@gmail.com</email>
      </contact>
      <contact enddate="04-24-2012T16:43:57.000-0400" grid="b1fe318c-b80f-44d0-8df0-4b0290c07744" op="DELETE" ts="04-24-2012T16:43:57.000-0400">
        <id>5</id>
        <name>pete</name>
        <city>king of prussia</city>
        <email>pete@gmail.com</email>
      </contact>
</batch>

Acknowledge Previously Fetched Channel Updates

The Acknowledge Previously Fetched Channel Updates operation acknowledges the receipt of a previously fetched batch of channel updates.

Additional Information: Multiple Channels: If the source is configured with multiple channels, instead send an HTTP POST request to: /universes/{universeId}/sources/{sourceId}/channels/{channelId}/updates/{updateId}/acknowledge. (Boomi maintains this form for backward compatibility - you cannot configure newly attached sources with multiple channels.)

Security Requirements: You must have one of the following MDM privileges:

Without Advanced Security:

  • MDM - Source Management
Authorizations:
basicAuthbearerAuth
path Parameters
universeId
any
Example: 851a6a64-6a88-4916-a5b7-d6a974d54318

Universe ID. Listed in the Repositories UI URL.

sourceId
any
Example: CRM_SYSTEM

Source ID. The source ID is listed on the Sources page in the user interface.

updateId
any
Example: 3

ID of the channel update to acknowledge

query Parameters
repositoryId
any

Repository ID. 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.

Responses

Response samples

Content type
application/xml
<?xml version="1.0" encoding="UTF-8"?>
<error>
  <message>Invalid request parameters or format</message>
</error>

Query Outbound Activity

The Query Outbound Activity operation lets you programmatically retrieve data about pending and delivered record update requests to outbound sources. The data aligns with information you can access in the user interface on the Reporting > Outbound Activity screen.

Additional Information: A delivery is recorded only upon acknowledgment by an integration process on behalf of the targeted source. Read Fetch Channel Updates for more information on automatic and Acknowledge Previously Fetched Channel Updates for more information on manual acknowledgement.

Security Requirements: You must have one of the following MDM privileges:

Without Advanced Security:

  • MDM - Activity Reporting
Authorizations:
basicAuthbearerAuth
path Parameters
universeId
any
Example: 851a6a64-6a88-4916-a5b7-d6a974d54318

Universe ID. Listed in the Repositories UI URL.

sourceId
any
Example: CRM_SYSTEM

Source ID. The source ID is listed on the Sources page in the user interface.

query Parameters
repositoryId
any

Repository ID. 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 Body schema: application/xml
required

The request body root element is <OutboundActivityRequest>.

Request parameters:

  • queryType — Status of the update requests you want to query. String. Required. Values are:

    • PENDING — Displays pending update requests for the specified universe and target source.
    • HISTORY — Displays delivered and acknowledged update requests for the specified universe and target source.

  • 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 Data Hub enforces a maximum of 200 requests per page regardless of the limit value. Integer. Optional.

  • sortBy — Indicates that you want to sort by a filter parameter. For example, createdDate. String. Optional.

  • sortAsc — Sorts results in ascending or descending order. Boolean. Optional.

    • true — sorts results in ascending order.
    • false — sorts results in descending order.

Query filter parameters:

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

  • deliveryId — Filters record updates based on the Delivery ID assigned when the batch of update requests is delivered. This filter only applies when the queryType is set to HISTORY. String. Optional.

  • grid — Filter by golden record ID. String. Optional.

  • createdDate — Filter by date and time at which the update request was created in the batch. Datetime. Optional. This tag wraps the to and from tags:

    • 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 createdRelativeTime filter is specified, it overrides this filter.

  • createdRelativeTime — Filters by a time frame relative to the current date and time. String. Optional. Values are: PAST_HOUR, PAST_24_HOURS, PAST_WEEK.

  • deliveryType — Filters by deliverable and undeliverable update requests only when queryType is PENDING. String. Optional.

    • UNDELIVERABLE — Held update requests are undeliverable. An update request is held if it is for a golden record that references a golden record that is not linked to a record in the source and then only if the underlying domain model enforces referential integrity for update requests.
    • DELIVERABLE — Pending update requests that are not held.

  • opType — Filters by operation type. String. Optional. Values are:

    • CREATE — filter by update requests for record creation.
    • UPDATE — filter by update requests for record changes.
    • DELETE — filter by update requests for record deletion.
    • RESTORE — filter by update requests for record restoration from end-dated to active status.
    • REJECT_DUPLICATE — filter by update requests to reject the update as a duplicate of existing source entities.
queryType
object (ChannelQueryType)
object (OutboundActivityFilter)
sortBy
string
sortAsc
boolean

Responses

Response Schema: application/xml
Array of objects (OutboundActivity)
resultCount
integer <int32>
totalCount
integer <int64>

Request samples

Content type
application/xml
<OutboundActivityRequest sortAsc="false" sortBy="createdDate">
   <queryType></queryType>
   <filter>
      <opType>CREATE</opType>
   </filter>
</OutboundActivityRequest>

Response samples

Content type
application/xml
<OutboundActivityResponse resultCount="5" totalCount="1000">
   <OutboundActivity>
      <id>4</id>
      <grid>539e13f5-4cab-4d83-8457-6f79c49a3828</grid>
      <title>Lola Rubin</title>
      <opType>CREATE</opType>
      <createdAt>2025-02-21T00:19:43Z</createdAt>
   </OutboundActivity>
   <OutboundActivity>
      <id>3</id>
      <grid>5cc30f9a-dfc7-4326-a299-61ac8c953177</grid>
      <title>Robert Reeves</title>
      <opType>CREATE</opType>
      <createdAt>2025-02-21T00:19:42Z</createdAt>
   </OutboundActivity>
</OutboundActivityResponse>

Retrieve real time outbound message by ID

Security Requirements: You must have one of the following MDM privileges:

Without Advanced Security:

  • MDM - Activity Reporting and MDM - View Data and MDM - Stewardship OR
  • MDM - Activity Reporting and MDM - View Data and MDM - Stewardship Management
Authorizations:
basicAuthbearerAuth
path Parameters
universeId
any
Example: 851a6a64-6a88-4916-a5b7-d6a974d54318

Universe ID. Listed in the Repositories UI URL.

sourceId
any
Example: CRM_SYSTEM

Source ID. The source ID is listed on the Sources page in the user interface.

messageId
any
Example: 3

ID of the message published for the update

query Parameters
repositoryId
any

Repository ID. 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.

Responses

Response Schema: application/xml
string

Response samples

Content type
application/xml
string

Propagate Channel Updates

The Propagate Channel Updates operation requests the propagation of source record update requests to a specific source on its channel for golden records in a universe (domain) under the authenticated account.

Security Requirements: You must have one of the following MDM privileges:

Without Advanced Security:

  • MDM - Source Management
Authorizations:
basicAuthbearerAuth
path Parameters
universeId
any
Example: 851a6a64-6a88-4916-a5b7-d6a974d54318

Universe ID. Listed in the Repositories UI URL.

sourceId
any
Example: CRM_SYSTEM

Source ID. The source ID is listed on the Sources page in the user interface.

query Parameters
repositoryId
any

Repository ID. 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 Body schema: application/xml
required

Requests for this operation are processed asynchronously. At any given time, processing only a single instance of manually propagated update requests can be in progress for a universe and source combination. Propagation of an update request for an individual golden record is subject to propagation rules configured for a given universe and source combination.

After receiving a request by the repository, you can obtain the processing status with a Get Channel Updates Status operation, and you can cancel processing with a Cancel Channel Updates operation.

Root element: <RecordSourceUpdateRequest>. If this element's recordStatus attribute value is ACTIVE (the default), propagation of update requests is limited to active golden records. If the value is END_DATED, propagation is limited to end-dated (inactive) golden records. Within <RecordSourceUpdateRequest>, each <recordId> (optional) specifies a golden record for which to propagate update requests by its ID.

<filter> sets query filter parameters and the query operator. The optional op attribute specifies the query operator: AND (all criteria) or OR (any criterion). Default is AND. The order in which you specify filter parameters in <filter> is insignificant.

Filter parameter types:

  • <createdDate> — Filter by date and time of golden record creation. <from> and <to> set the range (format yyyy-MM-dd'T'HH:mm:ss'Z'). Omitting <from> filters records created before <to>; omitting <to> filters records created after <from>.

  • <updatedDate> — Filter by date and time of last golden record update. Same <from>/<to> format and omission behavior as <createdDate>.

  • <fieldValue> — Filter by golden record field value. <fieldId> specifies the field ID; <operator> the operator; <value> the value (see below). Operators valid for all types: EQUALS. For all types except Reference and collection fields: NOT_EQUALS, IS_NOT_NULL, IS_NULL. Text/Long Text: CONTAINS, ENDS_WITH, STARTS_WITH. Integer/Float: GREATER_THAN, GREATER_THAN_EQUAL, LESS_THAN, LESS_THAN_EQUAL. Date/Date and Time/Time: BETWEEN. Enumeration: IS_INVALID. BETWEEN requires two <value> elements (date/time format varies by type). EQUALS with Enumeration allows multiple <value> elements. IS_INVALID, IS_NOT_NULL, IS_NULL do not use <value>. Boolean values: true or false.

  • <tags> — Filter by one or more tags via <tagName>. A golden record having any one of the specified tags meets the criteria.

  • <creatingSourceId> — Filter by creating source specified by its source ID.

  • <sourceLink> — Filter by presence or absence of links to a source. <sourceId> specifies the source; <linkType> is LINKED or NOT_LINKED. Note: If the universe has sources configured to allow multiple links to golden records, processing time for requests using <sourceLink> may be significantly longer.

  • <unresolvedReference> — Filter by presence of unresolved reference field data. <fieldId> specifies the reference field; <sourceId> is a source ID or @all (limits results to golden records for which all source contributions are unresolved). Note: You can find a field's ID on the model page's Fields tab in Boomi Data Hub; a source's ID on the Sources page.

Note: If the request body <RecordSourceUpdateRequest> is either empty or contains an empty <filter> and no <recordId> elements, propagation is requested for either all active or all end-dated golden records in the specified universe, depending on the recordStatus attribute value.

recordId
Array of strings
object (RecordQueryFilter)
recordStatus
object (RecordStatus)

Responses

Request samples

Content type
application/xml
Example

Specify golden records by applying a filter. Processing is asynchronous.

<RecordSourceUpdateRequest>
   <filter op="AND">
      <createdDate>
         <from>2023-01-01T00:00:00Z</from>
         <to>2023-12-31T23:59:59Z</to>
      </createdDate>
      <updatedDate>
         <from>2023-01-01T00:00:00Z</from>
         <to>2023-12-31T23:59:59Z</to>
      </updatedDate>
      <fieldValue>
         <fieldId>FIRST_NAME</fieldId>
         <operator>EQUALS</operator>
         <value>Sample Value</value>
         <value>Sample Value</value>
      </fieldValue>
      <fieldValue>
         <fieldId>FIRST_NAME</fieldId>
         <operator>EQUALS</operator>
         <value>Sample Value</value>
         <value>Sample Value</value>
      </fieldValue>
      <sourceLink>
         <sourceId>SFDC</sourceId>
         <linkType>LINKED</linkType>
      </sourceLink>
      <creatingSourceId>SFDC</creatingSourceId>
      <tags>
         <tagName>VIP_CUSTOMER</tagName>
         <tagName>VIP_CUSTOMER</tagName>
      </tags>
      <unresolvedReference>
         <sourceId>SFDC</sourceId>
         <fieldId>FIRST_NAME</fieldId>
      </unresolvedReference>
      <recordIds>
         <recordId>0fc4eb6d-f12c-4cdd-ba37-5475caed4887</recordId>
         <recordId>0fc4eb6d-f12c-4cdd-ba37-5475caed4887</recordId>
      </recordIds>
      <queryString>FIRST_NAME:John AND STATUS:ACTIVE</queryString>
   </filter>
</RecordSourceUpdateRequest>

Response samples

Content type
application/xml
147

Get Channel Updates Status

The Get Channel Updates Status operation retrieves by request ID, the status of a Propagate Channel Updates request.

Security Requirements: You must have one of the following MDM privileges:

Without Advanced Security:

  • MDM - Source Management OR
  • MDM - Activity Reporting
Authorizations:
basicAuthbearerAuth
path Parameters
universeId
any
Example: 851a6a64-6a88-4916-a5b7-d6a974d54318

Universe ID. Listed in the Repositories UI URL.

sourceId
any
Example: CRM_SYSTEM

Source ID. The source ID is listed on the Sources page in the user interface.

jobId
any
Example: 139

ID of the Propagate Channel Updates request. You can obtain this ID from the response body for that request.

query Parameters
repositoryId
any

Repository ID. 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.

Responses

Response Schema: application/xml
startDate
string
endDate
string
status
string
object (RecordIds)
totalCount
integer <int64>
successCount
integer <int64>
errorCount
integer <int64>

Response samples

Content type
application/xml
<ChannelUpdatesStatus successCount="1000" totalCount="1000" errorCount="1000">
   <startDate>2023-01-01T00:00:00Z</startDate>
   <endDate>2023-01-01T00:00:00Z</endDate>
   <status>COMPLETED_WITH_ERRORS</status>
   <erroredUpdates>
      <recordId>0fc4eb6d-f12c-4cdd-ba37-5475caed4887</recordId>
   </erroredUpdates>
</ChannelUpdatesStatus>

Cancel Channel Updates

The Cancel Channel Updates operation cancels a Propagate Channel Updates request specified by its ID.

Additional Information: This operation is applicable to a request with a status of SUBMITTED or PROCESSING. You can obtain the status using a Get Channel Updates Status request.

Note: You can implement requests for this operation in processes using the HTTP Client connector.

Security Requirements: You must have one of the following MDM privileges:

Without Advanced Security:

  • MDM - Source Management
Authorizations:
basicAuthbearerAuth
path Parameters
universeId
any
Example: 851a6a64-6a88-4916-a5b7-d6a974d54318

Universe ID. Listed in the Repositories UI URL.

sourceId
any
Example: CRM_SYSTEM

Source ID. The source ID is listed on the Sources page in the user interface.

jobId
any
Example: 139

ID of the Propagate Channel Updates request. You can obtain this ID from the response body for that request.

query Parameters
repositoryId
any

Repository ID. 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.

Responses

Response Schema: application/xml
string

Response samples

Content type
application/xml
<true/>