Cookies Settings

Loading

dnb-logo
Direct 2.0
Collapse

Processing JSON Change Notices

This page provides explanations for how to interpret and process change notices received (i.e., PUSH) by E-Mail, HTTPcallback and/or MQOutput.

What to do First

Add Monitoring Registration

This function allows a customer to specify one D-U-N-S Number, along with active monitoring and notification profiles, and initiates the monitoring process for that organization.

Feature Response

NOTE: The D&B Direct REST implementation uses the BadgerFish approach for JSON with some minor variations.

Specification

The following is a list of the possible data fields returned by this operation in the JSON response. Samples are provided for testing successful and failed retrieval, and to demonstrate the basic layout of a response. The data returned in samples may not represent actual values that this feature will deliver.

The volume of resulting change notices is dependent on the product/data field criteria (i.e. Monitoring Profile), volatility of the company being monitored, and the data update frequency (which may vary in certain countries). Change detection is currently based on the latest values as compared to previous values, and therefore is not cumulative from the date of registration.

Change notices are not cumulative. For extended notification periods (e.g. weekly), the change notice will only reflect the changes since the last notice. For example, if an element which is being monitored changes multiple times within a week, a weekly change notice would only reflect the difference between the final and last (weekly change notice) values.

NOTE: For level 2 Monitoring registrations, the service returns data layers in the format specified by the latest version of the corresponding service. For example, if the DCP_PREM data layer is being monitored and a new version of the Firmographic service is released, level 2 Monitoring attachments will reflect the newer DCP_PREM layout (if it changed).

Sample Change Notice(JSON)
Name Characteristics
ChangeNotice Aggregate
ChangeNotice @xsi:schemaLocation
ChangeNotice { TransactionDetail Aggregate, Required
ChangeNotice { TransactionDetail { ChangeNoticeID long, Required

A number assigned by the D&B service to uniquely identify this transaction.

ChangeNotice { TransactionDetail { ChangeNoticeDeliveryTimestamp dateTime, Required

The date and time when this request was submitted or the date and time when the requesting intermediary, such as a workflow manager or service bus, sent the message to the D&B function, i.e., the date and time when the xml document was created by the requesting intermediary.

END: ChangeNotice } TransactionDetail /Aggregate
ChangeNotice { ChangeNoticeDetail Aggregate, Required
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail Aggregate, Required (Infinite)
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { SubjectDetail Aggregate, Required
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { SubjectDetail { DUNSNumber string, up to 9 chars Pattern: {([0-9]*)}, Required

Records the duns number that is registered for Monitoring.

ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { SubjectDetail { PrincipalIdentificationNumberDetail Aggregate, Optional
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { SubjectDetail { PrincipalIdentificationNumberDetail @DNBCodeValue
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { SubjectDetail { PrincipalIdentificationNumberDetail { PrincipalIdentificationNumber string, Optional

A number assigned by an external body or by D&B which either uniquely identifies or helps to identify an individual.

END:ChangeNotice } ChangeNoticeDetail } SubjectChangeDetail } SubjectDetail } PrincipalIdentificationNumberDetail /Aggregate
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { SubjectDetail { CountryISOAlpha2Code string, at least 2 chars, up to 2 chars, Required

The two-letter country code, defined in the ISO 3166-1 scheme published by International Organization for Standardization (ISO)identifying the country of the inquired subject.

ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { SubjectDetail { OrganizationPrimaryName Aggregate, Optional (Infinite)

An entry loop which can repeat multiple times to allow the recording of a single name by which the organization is primarily known / identified in different languages and/or writing scripts.

ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { SubjectDetail { OrganizationPrimaryName { OrganizationName string, up to 256 chars, Required
END: ChangeNotice } ChangeNoticeDetail } SubjectChangeDetail } SubjectDetail } OrganizationPrimaryName /Aggregate
END: ChangeNotice } ChangeNoticeDetail } SubjectChangeDetail } SubjectDetail /Aggregate
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { SubjectCategoryText string, up to 32 chars, Optional

An alphanumeric value identifying the category in which the Customer has classified the subject.

Possible values: High; Medium; Low

ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { LanguageCode integer, up to 7 digits, Required

A D&B code value that defines a language in which the specified product is available.

ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { MonitoringProfileDetail Aggregate, Required
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { MonitoringProfileDetail { MonitoringProfileID integer, Required

A number that uniquely identifies a set of events and their thresholds, used to monitor a DUNS or a set of DUNS.

ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { MonitoringProfileDetail { DNBProductID string, up to 64 chars, Required

An alphanumeric string that uniquely identifies this product.

ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { MonitoringProfileDetail { MonitoringLevel MonitoringLevelTextEnum up to 16 chars, Required

A alphanumeric string which determines the level of details that the customer will receive during a change event

Possible values: Level1; Level2

END: ChangeNotice } ChangeNoticeDetail } SubjectChangeDetail } MonitoringProfileDetail /Aggregate
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent Aggregate, Required (Infinite)
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { ChangeEventID long, Required
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { ChangeDetectionTimestamp dateTime, Required

The date and time when this notification has been generated

ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { ElementName string, up to 64 chars, Required
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { PCMElementXPATHText string, up to 3000 chars, Required
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { Element String, Optional (Infinite)
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { Element @ChangeType
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange Aggregate, Optional
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { DUNSNumber string, up to 9 chars Pattern: {([0-9]*)}, Required
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { ChangeType string, Required
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { ChangeReasonText string, up to 256 chars, Optional
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { ChangeReasonText @DNBCodeValue Optional
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { ChangeReasonText @DNBCodeTableNumber Optional
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { GlobalUltimateOrganization Aggregate, Optional
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { GlobalUltimateOrganization { AssociationTypeText string, up to 256 chars, Optional

Text that defines the nature of the relationship of the linked organization to the business subject, e.g., parent, HQ, Joint parent

Possible values: GlobalUltimate; DomesticUltimate; Headquarters; Parent; Branch; Division; Subsidiary

ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { GlobalUltimateOrganization { AssociationTypeText @DNBCodeValue
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { GlobalUltimateOrganization { AssociationTypeText @DNBCodeTableNumber
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { GlobalUltimateOrganization { DUNSNumber string, up to 9 chars Pattern: {([0-9]*)}, Required

The D-U-N-S Number is D&B's identification number, which provides unique identification of this organization, in accordance with the Data Universal Numbering System (D-U-N-S).

END: ChangeNotice } ChangeNoticeDetail } SubjectChangeDetail } ChangeEvent } LinkageChange } GlobalUltimateOrganization /Aggregate
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { FormerGlobalUltimateOrganization Aggregate, Optional
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { FormerGlobalUltimateOrganization { AssociationTypeText string, up to 256 chars, Optional

Text that defines the nature of the relationship of the linked organization to the business subject, e.g., parent, HQ, Joint parent

Possible values: GlobalUltimate; DomesticUltimate; Headquarters; Parent; Branch; Division; Subsidiary

ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { FormerGlobalUltimateOrganization { AssociationTypeText @DNBCodeValue
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { FormerGlobalUltimateOrganization { AssociationTypeText @DNBCodeTableNumber
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { FormerGlobalUltimateOrganization { DUNSNumber string, up to 9 chars Pattern: {([0-9]*)}, Required

The D-U-N-S Number is D&B's identification number, which provides unique identification of this organization, in accordance with the Data Universal Numbering System (D-U-N-S).

END: ChangeNotice } ChangeNoticeDetail } SubjectChangeDetail } ChangeEvent } LinkageChange } FormerGlobalUltimateOrganization /Aggregate
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { UpwardFamilyMemberOrganization Aggregate, Optional
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { UpwardFamilyMemberOrganization { AssociationTypeText string, up to 256 chars, Optional

Text that defines the nature of the relationship of the linked organization to the business subject, e.g., parent, HQ, Joint parent

Possible values: GlobalUltimate; DomesticUltimate; Headquarters; Parent; Branch; Division; Subsidiary

ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { UpwardFamilyMemberOrganization { AssociationTypeText @DNBCodeValue
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { UpwardFamilyMemberOrganization { AssociationTypeText @DNBCodeTableNumber
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { UpwardFamilyMemberOrganization { DUNSNumber string, up to 9 chars Pattern: {([0-9]*)}, Required

The D-U-N-S Number is D&B's identification number, which provides unique identification of this organization, in accordance with the Data Universal Numbering System (D-U-N-S).

END: ChangeNotice } ChangeNoticeDetail } SubjectChangeDetail } ChangeEvent } LinkageChange } UpwardFamilyMemberOrganization /Aggregate
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { FormerUpwardFamilyMemberOrganization Aggregate, Optional
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { FormerUpwardFamilyMemberOrganization { AssociationTypeText string, up to 256 chars, Optional

Text that defines the nature of the relationship of the linked organization to the business subject, e.g., parent, HQ, Joint parent

Possible values: GlobalUltimate; DomesticUltimate; Headquarters; Parent; Branch; Division; Subsidiary

ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { FormerUpwardFamilyMemberOrganization { AssociationTypeText @DNBCodeValue
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { FormerUpwardFamilyMemberOrganization { AssociationTypeText @DNBCodeTableNumber
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { FormerUpwardFamilyMemberOrganization { DUNSNumber string, up to 9 chars Pattern: {([0-9]*)}, Required

The D-U-N-S Number is D&B's identification number, which provides unique identification of this organization, in accordance with the Data Universal Numbering System (D-U-N-S).

END: ChangeNotice } ChangeNoticeDetail } SubjectChangeDetail } ChangeEvent } LinkageChange } FormerUpwardFamilyMemberOrganization /Aggregate
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { ChildrenSummary Aggregate, Optional (Infinite)

An entry loop which can repeat multiple times to allow the recording of the number of children of various types for the Subject.

ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { ChildrenSummary { ChildrenQuantity integer, up to 8 digits, Optional

The total number of children of the linked Family Tree Subject of the type specified by Children Type Text.

ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ChangeEvent { LinkageChange { ChildrenSummary { DirectChildrenIndicator boolean, Optional

When TRUE (set to 1)it indicates immediate children only.

END: ChangeNotice } ChangeNoticeDetail } SubjectChangeDetail } ChangeEvent } LinkageChange } ChildrenSummary /Aggregate
END: ChangeNotice } ChangeNoticeDetail } SubjectChangeDetail } ChangeEvent } LinkageChange /Aggregate
END: ChangeNotice } ChangeNoticeDetail } SubjectChangeDetail } ChangeEvent /Aggregate
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ObjectAttachment Aggregate, Optional
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ObjectAttachment { ContentObject base64Binary, Required
ChangeNotice { ChangeNoticeDetail { SubjectChangeDetail { ObjectAttachment { ObjectFormatCode integer, up to 7 digits, Required

SCoTS: 126 [Object Format]

END: ChangeNotice } ChangeNoticeDetail } SubjectChangeDetail } ObjectAttachment /Aggregate
END: ChangeNotice } ChangeNoticeDetail } SubjectChangeDetail /Aggregate
END: ChangeNotice } ChangeNoticeDetail /Aggregate
END: ChangeNotice /Aggregate

The embedded ObjectAttachment field will contain a copy of the complete data layer in Base64 encoded format whenever level 2 monitoring is specified on the initial AddMonitoringRegistration call.

NOTE: The OrderProductResponse@ServiceVersionNumber value in the object attachment will NOT match the version of the data layer when retrieved from it's corresponding service.

HTTP Callback Authentication

Using the UserID and PasswordText values provided in the User Preference profile, the D&B service will perform HTTP Basic Authentication before posting the change notice to the URL stored in the PreferenceValueText of field the User Preference profile. Here are the steps that will be followed:

1. The UserID and PasswordText will be combined into a string "username:password",

2. The resulting string is then encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line,

3. The authorization method and a space (i.e. "Basic ") is then placed before the encoded string.

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==