Loading

dnb-logo
Direct 2.0
Collapse

List User Preference

IMPORTANT: Version 2.2 is the latest available service for Direct 2.0 customers.

This function allows a customer to review active user preferences.

Update History

No modifications have been made to this data layer since the initial release.

What to do First

Feature Request

IMPORTANT: Please see the new Online Services Security Enhancement Release, effective November 09, 2020.

Data Layer Entitlement

For customers in U.S. and Canadian markets, the API is provisioned for specific collections of products, reports, and/or features (collectively referred to as data layers) for production and trial usage. Entitlement is not required for testing in the sandbox environment.

  • This particular feature does not require entitlement for production and trial usage for D&B Direct 2.0 customers.

Specification

Sample Request (List)
GET https://direct.dnb.com/V2.2/userpreference?SortDirectionText=Ascending&ApplicationAreaName=Monitoring&CreatedToDate=2013-09-26&SortBasisText=UserPreferenceName&CreatedFromDate=2013-09-25
Authorization: <MyToken>

Name Characteristics
{version} Element
ApplicationTransactionID string up to 64 chars., Optional
TransactionTimestamp DateTimestamp, Optional
SubmittingOfficeID string up to 64 chars., Optional
PreferenceType PreferenceTypeEnum, Optional
ApplicationAreaName ApplicationAreaEnum, Optional
PreferenceName string up to 64 chars., Optional
PreferenceDescription string up to 256 chars., Optional
PreferenceValueText string up to 1024 chars., Optional
CreatedFromDate date, Optional

Records the start date of the date range to list the user preference

CreatedToDate date, Optional

Records the enddate of the date range to list the user preference

PreferenceStatusText PreferenceStatusTextEnum, Optional

Records the status of the monitoring profile

DefaultPreference boolean, Optional
SortBasisText PreferenceSortBasisEnum, Optional

Records the list of fields based on which sorting is possible

SortDirectionText SortDirectionEnum, Optional

Records the direction of sorting. Possbile values are Ascending, Descending

CandidatePerPageMaximumQuantity int Less than or equal to 1000., Optional

Records the maximum quantity that can be displayed per page

CandidateDisplayStartSequenceNumber int, Optional

Records the Display sequence number of the results

Endpoint

Use the following endpoint for requesting this feature. The {version} is dependent on the underlying service delivering the response.

Endpoint (User)
GET https://direct.dnb.com/V{version}/userpreference

Testing

This operation has no additional limits or restrictions in the D&B Direct sandbox (test) environment.

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.

Sample Response (List)
{"ListPreferenceResponse": {
   "@ServiceVersionNumber": "2.2",
   "TransactionDetail":    {
      "ServiceTransactionID": "Id-07746d925244637c019b330c-1",
      "TransactionTimestamp": "2013-09-26T12:40:28.662-04:00"
   },
   "TransactionResult":    {
      "SeverityText": "Information",
      "ResultID": "CM000",
      "ResultText": "Success"
   },
   "ListPreferenceResponseDetail":    {
      "CandidateMatchedQuantity": 2,
      "CandidateReturnedQuantity": 2,
      "PreferenceDetail":       [
                  {
            "PreferenceType": "Email",
            "ApplicationAreaName": "Monitoring",
            "PreferenceName": "John-email",
            "PreferenceDescription": "John Email",
            "PreferenceValueText": "john@mycompany.com",
            "PreferenceStatusText": "Active",
            "PreferenceCreatedDate": "2013-09-26",
            "DefaultPreference": false,
            "DisplaySequence": 1
         },
                  {
            "PreferenceType": "HTTPCallBack",
            "ApplicationAreaName": "Monitoring",
            "PreferenceName": "MyCompany-HTTPCallBack",
            "PreferenceDescription": "MyCompany's HTTPCallBack URI",
            "PreferenceValueText": "https://www.mycompany.com/uri",
            "PreferenceStatusText": "Active",
            "PreferenceCreatedDate": "2013-09-26",
            "DefaultPreference": false,
            "DisplaySequence": 2
         }
      ]
   }
}}
Name Characteristics
ListPreferenceResponse Aggregate
ListPreferenceResponse@ServiceVersionNumber Attribute
ListPreferenceResponse { TransactionDetail Aggregate, Required
ListPreferenceResponse { TransactionDetail { ApplicationTransactionID string up to 64 chars., Optional
ListPreferenceResponse { TransactionDetail { ServiceTransactionID string up to 64 chars., Required
ListPreferenceResponse { TransactionDetail { TransactionTimestamp DateTimestamp, Required
END: ListPreferenceResponse } TransactionDetail /Aggregate
ListPreferenceResponse { TransactionResult Aggregate, Required
ListPreferenceResponse { TransactionResult { SeverityText string, Required
ListPreferenceResponse { TransactionResult { ResultID string up to 32 chars., Required
ListPreferenceResponse { TransactionResult { ResultText string up to 512 chars., Optional
ListPreferenceResponse { TransactionResult { ResultMessage Aggregate, Optional (Array)
ListPreferenceResponse { TransactionResult { ResultMessage { ResultDescription string up to 512 chars., Required
END: ListPreferenceResponse } TransactionResult } ResultMessage /Aggregate
END: ListPreferenceResponse } TransactionResult /Aggregate
ListPreferenceResponse { ListPreferenceResponseDetail Aggregate, Optional
ListPreferenceResponse { ListPreferenceResponseDetail { CandidateMatchedQuantity int up to 6 digits., Required

The number of registrations listed as possible matches in the result set based on the search criteria in the Customer/User request.

ListPreferenceResponse { ListPreferenceResponseDetail { CandidateReturnedQuantity int up to 6 digits., Required

The number of registrations returned in the result set based on the search criteria in the Customer/User request.

ListPreferenceResponse { ListPreferenceResponseDetail { PreferenceDetail Aggregate, Optional (Array)
ListPreferenceResponse { ListPreferenceResponseDetail { PreferenceDetail { PreferenceType PreferenceTypeEnum, Required
ListPreferenceResponse { ListPreferenceResponseDetail { PreferenceDetail { ApplicationAreaName ApplicationAreaEnum, Optional
ListPreferenceResponse { ListPreferenceResponseDetail { PreferenceDetail { PreferenceName string up to 64 chars., Optional
ListPreferenceResponse { ListPreferenceResponseDetail { PreferenceDetail { PreferenceDescription string up to 256 chars., Optional
ListPreferenceResponse { ListPreferenceResponseDetail { PreferenceDetail { PreferenceValueText string up to 256 chars., Required
ListPreferenceResponse { ListPreferenceResponseDetail { PreferenceDetail { UserCredentials Aggregate, Optional
ListPreferenceResponse { ListPreferenceResponseDetail { PreferenceDetail { UserCredentials { UserID string up to 64 chars., Required
ListPreferenceResponse { ListPreferenceResponseDetail { PreferenceDetail { UserCredentials { PasswordText string up to 64 chars., Required
END: ListPreferenceResponse } ListPreferenceResponseDetail } PreferenceDetail } UserCredentials /Aggregate
ListPreferenceResponse { ListPreferenceResponseDetail { PreferenceDetail { PreferenceStatusText PreferenceStatusTextEnum, Required

Records the status of the monitoring profile

ListPreferenceResponse { ListPreferenceResponseDetail { PreferenceDetail { PreferenceCreatedDate date, Required

Records the start date of the date range to list the Monitoring profiles

ListPreferenceResponse { ListPreferenceResponseDetail { PreferenceDetail { PreferenceCreatedDate@DatePrecisionText Attribute
ListPreferenceResponse { ListPreferenceResponseDetail { PreferenceDetail { PreferenceCreatedDate@DatePrecisionDNBCodeValue Attribute
ListPreferenceResponse { ListPreferenceResponseDetail { PreferenceDetail { PreferenceCreatedDate@DatePrecisionDNBCodeTableNumber Attribute
ListPreferenceResponse { ListPreferenceResponseDetail { PreferenceDetail { DefaultPreference boolean, Optional
ListPreferenceResponse { ListPreferenceResponseDetail { PreferenceDetail { DisplaySequence int up to 3 digits., Optional

Records the display sequence number of the results

END: ListPreferenceResponse } ListPreferenceResponseDetail } PreferenceDetail /Aggregate
END: ListPreferenceResponse } ListPreferenceResponseDetail /Aggregate
END: ListPreferenceResponse /Aggregate

Response Codes & Error Handling

Successful service requests will return a CM000 response code in the TransactionResult ResultID field. Otherwise, one of the D&B Direct standard response codes will be returned.

This operation may return the following response codes: CM002, CM004, CM018, and SC001-SC009.