Cookies Settings

Loading

dnb-logo
Direct 2.0
Collapse

D&B Total Loss Predictor

Total Loss Predictor (TLP) identifies and quickly assesses companies that have a high risk of defaulting on their very first payment, which could be for a number of reasons, including an inability, unwillingness, or intent not to pay.

See the Predictive Analytics page for more information on Dun & Bradstreet's risk scores.

Update History

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

Product Request

IMPORTANT: Due to a known issue, please do not include request values for SubmittingOfficeID.

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

Overview

When requesting this feature, a valid D&B D-U-N-S Number for a company and the appropriate product code will be required. For improved performance, include a country code of "US".

A trade up option exists to request data for a headquarters location when the requested organization is a branch.

Global Availability

This data layer is only available for businesses domiciled in the United States.

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 product is entitled as "D&B Total Loss Predictor" for D&B Direct 2.0 customers.

For customers in the UK, Ireland, Belgium, Netherlands and Luxembourg markets, the API is provisioned as a specific set of data layers for production, trial, and sandbox usage.

  • This particular data layer is NOT included in the D&B Direct Onboard suite.

Specification

Sample Request (TLP)
GET https://direct.dnb.com/V5.0/organizations/804735132/products/TLP
Authorization: <My Token>
Name Characteristics
{version} Element
ApplicationTransactionID string, up to 64 chars, Optional

A number assigned by the calling application to uniquely identify this request.

TransactionTimestamp DateTimestamp, Optional

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

SubmittingOfficeID string, up to 64 chars, Optional

A number that identifies the system or the software application from where this request originated. / A number used to uniquely identfy the D&B business segment or delivery channel from where this request originated.

{DUNS} string, up to 15 chars Pattern: {([0-9a-zA-Z]*)}, 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).

CountryISOAlpha2Code string, at least 2 chars up to 2 chars, Optional

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

{productID} string, Required

An alphanumeric string that uniquely identifies the product being requested.

LanguagePreferenceCode integer, up to 7 digits, Optional

A D&B code value that defines the language in which the customer wants this product to be rendered.

Possible values: 39 [English]

OrderReasonCode integer, up to 7 digits, Optional

Possible values: 6332 [Credit Decision]; 6333 [Assessment of credit solvency for intended business connection]; 6334 [Assessment of credit solvency for ongoing business connection]; 6335 [Debt Collection]; 6336 [Commercial Credit Insurance]; 6337 [Insurance Contract]; 6338 [Leasing Agreement]; 6339 [Rental Agreement]

TradeUpIndicator boolean, Optional

When 'true' indicates that the customer has requested that D&B return the data for the Headquarters when the requested organization is a Branch. When 'false' indicates that the customer has not requested that D&B return the data for the Headquarters when the requested organization is a Branch; however as this is the assumed condition there is no requirement to create this tag to represent this fact. Note: There are D&B WorldWide Network operations where the Headquarters information will be returned automatically, regardless of the customer request.

Possible values: true; false

ArchiveProductOptOutIndicator boolean, Optional

When 'true' indicates that the product being ordered is not to be stored. When 'false' indicates that the product being ordered is to be stored; however as this is the assumed condition there is no requirement to create this tag to represent this fact.

Possible values: true; false

ExtendArchivePeriodIndicator boolean, Optional

When 'true' the duration to archive the data is to be extended. Note: There is an additional cost for extending the archival period of the data purchased. When 'false' the duration to archive the data is not to be extended.

Possible values: true; false

CustomerReferenceText-n string, up to 240 chars, Optional (up to 5x)

A freeform reference string provided by the customer to be linked to the product in order to support subsequent order reconciliation.

CustomerBillingEndorsementText string, at least 1 chars, up to 240 chars, Optional

Text that is filled in by customer and commonly contains requesting individual or department name, or customer's own account/reference number and/or name for the case on which the product was provided.This text is a reference used during the billing process.

Endpoint

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

NOTE: While "organizations" is part of this endpoint, there is no service by this name. Many D&B Direct calls have a similar structure; however, the {version} component is based on the SERVICE to which a given product is associated.

REST (Assessment)
GET https://direct.dnb.com/V{version}/organizations/{DUNS}/products/{productID}

Testing

Sandbox

The following parameters may be used for D&B Direct 2.0 developer sandbox requests to retrieve successful responses. The data returned from sandbox requests may not represent actual values that this feature will deliver.

D-U-N-S Number (Country Code)
804735132 (US); 362241452 (US)

Trials

When conducting testing in the production environment during a trial period, product requests will be limited to the local market of the customer.

Production

A set of D-U-N-S Numbers is available to D&B Direct 2.0 customers for performing non-billable transactions in the production environment.

Product Response

While data for a particular company may not contain values for each of the business elements, there may be items that are considered by D&B to be "essential" to yield the maximum benefit of a data layer. If any of these essential elements do not contain a value for a particular company, a PD005 response code will be returned, and your organization will not incur a usage credit for the request.

For all codified data delivered by D&B Direct, the response package will include the decoded text value as a data element with the code value attached as an attribute. Refer to the Reference Data Service for access to the D&B standard code tables.

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.

NOTE: The D-U-N-S Number returned in the response will be a nine-digit zero-padded, numeric value.

Sample Response (TLP)
{"OrderProductResponse": {
  "@ServiceVersionNumber": "5.0",
  "TransactionDetail":   {
    "ServiceTransactionID": "Id-c8f4206f52d58b6610cb1240-2",
    "TransactionTimestamp": "2014-01-14T14:09:27.430-05:00"
  },
  "TransactionResult":   {
    "SeverityText": "Information",
    "ResultID": "CM000",
    "ResultText": "Success"
  },
  "OrderProductResponseDetail":   {
    "InquiryDetail":     {
      "DUNSNumber": "804735132",
      "CountryISOAlpha2Code": "US"
    },
    "Product":     {
      "DNBProductID": "TLP",
      "Organization":       {
        "SubjectHeader": {"DUNSNumber": "804735132"},
        "Telecommunication": {"TelephoneNumber": [        {
          "TelecommunicationNumber": "(650) 555-0000",
          "InternationalDialingCode": "1"
        }]},
        "Location": {"PrimaryAddress": [        {
          "StreetAddressLine": [{"LineText": "492 Koller St"}],
          "PrimaryTownName": "San Francisco",
          "CountryISOAlpha2Code": "US",
          "TerritoryAbbreviatedName": "CA",
          "PostalCode": "94110",
          "TerritoryOfficialName": "California"
        }]},
        "OrganizationName": {"OrganizationPrimaryName": [{"OrganizationName": {"$": "Gorman Manufacturing Company, Inc."}}]},
        "OrganizationDetail": {"FamilyTreeMemberRole":         [
          {"FamilyTreeMemberRoleText":           {
            "@DNBCodeValue": 12775,
            "$": "Global Ultimate"
          }},
          {"FamilyTreeMemberRoleText":           {
            "@DNBCodeValue": 12773,
            "$": "Parent"
          }},
          {"FamilyTreeMemberRoleText":           {
            "@DNBCodeValue": 12774,
            "$": "Domestic Ultimate"
          }}
        ]},
        "Assessment": {"TotalLossPredictorScore":         {
          "ScoreTimestamp": "2014-01-14T14:09:27.316-05:00",
          "RawScore": 2449,
          "ClassScore": "07",
          "RiskIncidencePercentage": 5.1,
          "ScoreCommentary":           [
                        {
              "CommentaryText":               {
                "@DNBCodeValue": 26209,
                "$": "Proportion of recent past due balances reported"
              },
              "DisplaySequence": 1
            },
                        {
              "CommentaryText":               {
                "@DNBCodeValue": 26205,
                "$": "Some firmographic data differs from available external data sources"
              },
              "DisplaySequence": 2
            },
                        {
              "CommentaryText":               {
                "@DNBCodeValue": 26092,
                "$": "Evidence of Negative trade"
              },
              "DisplaySequence": 3
            },
                        {
              "CommentaryText":               {
                "@DNBCodeValue": 26204,
                "$": "Reported high credit amount"
              },
              "DisplaySequence": 4
            }
          ]
        }}
      }
    }
  }
}}
Name Characteristics
OrderProductResponse { OrderProductResponseDetail { Product { Organization { Assessment { TotalLossPredictorScore { ScoreTimestamp date & time, Optional

The date and time when the risk scores were assigned to this subject. In the event that the risk scores could not be assigned, this is the date and time when the reason was recorded explaining why the score was not assigned.

OrderProductResponse { OrderProductResponseDetail { Product { Organization { Assessment { TotalLossPredictorScore { RawScore long, Optional

A numeric value that predicts the likelihood that the risk will occur.

OrderProductResponse { OrderProductResponseDetail { Product { Organization { Assessment { TotalLossPredictorScore { ClassScore string, up to 3 chars, Optional

A numeric value from 1 to 10 that succinctly expresses the likelihood of risk by specifying in which risk group this organization belongs. In other words, it specifies where this organization falls in a statistical distribution of all businesses (e.g, a bell curve, a half-normal distribution). A value of 1 denotes lowest risk and a value of 10 denotes highest risk.

OrderProductResponse { OrderProductResponseDetail { Product { Organization { Assessment { TotalLossPredictorScore { RiskIncidencePercentage decimal, up to 10 digits, maximum of 5 decimal places, Optional

A percentage that expresses the likelihood that the inferred risk (e.g., payment delinquency, discontinued operations) will occur for this organization. This percentage is determined based on which range this organization's score falls within a pre-determined set of score ranges. The ranges and percentages are determined through analysis of historical events.

OrderProductResponse { OrderProductResponseDetail { Product { Organization { Assessment { TotalLossPredictorScore { ScoreCommentary Aggregate, Optional (Infinite)

An entry loop which can repeat multiple times to allow the recording of primary reasons for the score.

OrderProductResponse { OrderProductResponseDetail { Product { Organization { Assessment { TotalLossPredictorScore { ScoreCommentary { CommentaryText string, up to 256 chars, Optional

Text that explains the primary reasons for the score.

OrderProductResponse { OrderProductResponseDetail { Product { Organization { Assessment { TotalLossPredictorScore { ScoreCommentary { CommentaryText @DNBCodeValue integer, up to 7 digits, Attribute (1x)
OrderProductResponse { OrderProductResponseDetail { Product { Organization { Assessment { TotalLossPredictorScore { ScoreCommentary { CommentaryText @DNBCodeTableNumber integer, up to 7 digits, Attribute (1x)
OrderProductResponse { OrderProductResponseDetail { Product { Organization { Assessment { TotalLossPredictorScore { ScoreCommentary { DisplaySequence integer, up to 3 digits, Optional

A number which may be used to define the order in which the reason code should be presented relative to any other occurrences of reason code where the lower the number the earlier the data is presented.

END:OrderProductResponse } OrderProductResponseDetail } Product } Organization } Assessment } TotalLossPredictorScore } ScoreCommentary /Aggregate
OrderProductResponse { OrderProductResponseDetail { Product { Organization { Assessment { TotalLossPredictorScore { ScoreOverrideReason Aggregate, Optional (Infinite)

An entry loop which can repeat multiple times to allow the recording of explanations stating why the risk score replaced the originally calculated value. The override reason can be recorded as a result of a manual adjustment or system rule.

OrderProductResponse { OrderProductResponseDetail { Product { Organization { Assessment { TotalLossPredictorScore { ScoreOverrideReason { ScoreOverrideReasonText string, up to 256 chars, Optional

Text which defines a generic reason for a rating override to provide a globally consistent view of the reason for the override.

OrderProductResponse { OrderProductResponseDetail { Product { Organization { Assessment { TotalLossPredictorScore { ScoreOverrideReason { ScoreOverrideReasonText @DNBCodeValue integer, up to 7 digits, Attribute (1x)

Legend: [C] = may be included in a Custom Data product; [M] = may be referenced by the Monitoring process; [M+] = Monitored using an aggregate or attribute XPath.

Lists of possible values (when present) are subject to change. Additional values not presented in this documentation may be delivered in the response and should be anticipated in any implementation.

Empty/NULL Values

A NULL returned for an element indicates that the information was not provided to D&B when the related data items were collected. The absence of a value for a particular item should not be considered indicative of any implied value (e.g., NULL for a boolean indicator is NOT the same as a value of 'false').

Currency Codes/Units

Whenever financial statement data is included in a response, each individual business element (ItemAmount) should be inspected for currency code and unit values (CurrencyISOAlpha3Code and UnitOfSize). If a given element does not include these attributes, the values provided in the statement header should be utilized.

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: CM001-CM005, CM007-CM012, CM014, CM017, CM018, PD001, PD003, PD005, PD006, PD015, PD016,PD019 and SC001-SC012.

IMPORTANT: PD006 code - Applicable only for US/CA cases when TradeUpIndicator="true" for Risk packets.

D&B Direct 2.0 API requests are provided on a metered basis; and may require entitlement prior to use in the production environment. In addition, a concurrency limit (QPS) is monitored to ensure that it is not exceeded. An error code will be returned in the event that a transaction is throttled.

Qualified usage (e.g., a successful response) is tracked and billed according to the terms & conditions of the customer's contract. The response codes CM000, CM010, PD002 and PD015 are considered successful. A built-in feature exists to prevent duplicate billing when multiple successful requests with the same D-U-N-S Number and product code are submitted on the same calendar day (which is based on Eastern Standard Time [GMT-5]).

Retrieving Archived Copies

An option exists to retain the results from all successful requests for this product in a Product Request Archive, which may be retrieved without incurring additional usage charges.

NOTE: The default value for ArchiveProductOptOutIndicator is 'true', indicating that the request will NOT be automatically archived.

Business Elements

While D&B Direct uses a product canonical naming model in the request/response, many customers may be more familiar with the following business element labels.

This product will also return a set of standard elements (e.g. D-U-N-S Number, Organization Name, Trade Styles, Family Tree Role, Primary Address, Mailing Address, Telephone Number, Fax Number, etc.) in addition to the business elements listed.

Name Description
Total Loss Predictor Class Score A one digit number from 0 to 5 assigned to the business based on information in D&B's file. The higher the class score the greater the likelihood that the organization will not pay other commercial business

PCM XPath: //Organization/ Assessment/ TotalLossPredictorScore/ ClassScore

Total Loss Predictor Raw Score Records the most recent risk scores that are assigned to this organization on a given date/time that predicts the likelihood that the organization will not pay other commercial businesses, which affects financial institutions and other industries that ext

PCM XPath: //Organization/ Assessment/ TotalLossPredictorScore/ RawScore

Total Loss Predictor Score Commentary Text Text that explains the primary reasons the subject business was assigned the Total Loss Predictor Score

PCM XPath: //Organization/ Assessment/ TotalLossPredictorScore/ ScoreCommentary/ CommentaryText

Total Loss Predictor Score Date The date on which the score was calculated.

PCM XPath: //Organization/ Assessment/ TotalLossPredictorScore/ ScoreTimestamp

Total Loss Predictor Score Override Reason Text Text that provides an explanation for why an instance of the Total Loss Predictor Score was overridden on the subject organization

PCM XPath: //Organization/ Assessment/ TotalLossPredictorScore/ ScoreOverrideReason/ ScoreOverrideReasonText

Total Loss Predictor Score Risk Incidence Percentage A percentage that expresses the likelihood that the organization will not pay other commercial businesses

PCM XPath: //Organization/ Assessment/ TotalLossPredictorScore/ RiskIncidencePercentage

The preceding list is not presented in the order, nor manner, in which the information is packaged and delivered via the D&B Direct API. Legend: [C] = may be included in a Custom Data product; [M] = may be referenced by the Monitoring process; [M+] = Monitored using an aggregate or attribute XPath.

Standard Elements

Whenever a D&B Direct data or report product request returns a single D-U-N-S Number, several business elements pertaining to that company will be included with the results.

These elements include D-U-N-S Number*, Organization Name, Primary Address** (including street, city, state, postal code, country), Mailing Address** (including street, city, state, postal code, county), Telephone Number, Fax Number, Trade Styles (up to five), Family Tree Role (HQ, branch), a Standalone Organization Indicator(true/false) and the PortfolioAssetID***.

All standard elements (with the exception of Family Tree Role and PortfolioAssetID) may be referenced by the Monitoring process.

* The D-U-N-S Number of the organization referenced in the results. In the case of a trade up, this will be the headquarters D-U-N-S Number.

** Addresses are returned as they are recieved by D&B and therefore may not conform to local postal formatting specifications.

*** This is an identification number that can be used to retrieve a given results package at a later date from the Product Request Archive (if/when that feature is enabled in a request).

Name Description
D-U-N-S Number 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). This DUNS Number represents the business entity.
Country Code The two-letter country code, defined by the International Organization for Standardization (ISO) ISO 3166-1 scheme identifying the country of the business entity.
County Name Text recording the name of the county in which the business is located.
Family Tree Member Role Text recording of various parts that the Subject plays as a member of an ownership structured family tree.
FAX Number The FAX number of the business.
FAX Number International Dialing Code The FAX number international dialing code of the business.
Mailing Country Code The two-letter country code, defined by the International Organization for Standardization (ISO) ISO 3166-1 scheme identifying the country which the business uses for mailing purposes.
Mailing County Name Text recording the name of the county which the business uses for mailing purposes.
Mailing Postal Code An identifier used by the local country Postal Authority which the business uses for mailing purposes.
Mailing Street Text recording an address which is mainly utilized for the purpose of mail delivery to the business. This usually includes a Post Office Box number or similar mailing details.
Mailing Street (2) Text recording an address which is mainly utilized for the purpose of mail delivery to the business. This usually includes a Post Office Box number or similar mailing details.
Mailing Territory Abbreviation Text recording the shortened name of the locally governed area which forms part of a centrally governed nation which the business uses for mailing purposes.
Mailing Territory Name Text recording the name of the locally governed area which forms part of a centrally governed nation which the business uses for mailing purposes.
Mailing Town Name The address number, or post office box number, and street name which a business uses for mailing purposes.
Postal Code An identifier used by the local country Postal Authority to identify where the business is located.
Primary Business Name Text recording of a single name by which the organization is primarily known or identified.
Standalone Organization Indicator When true indicates that this organization is not a member of a legal family tree. The Subject has no Parent Company, no subsidiaries or no branch/division locations.
Street Address Text recording the address number, or post office box number and street name where the business is located.
Street Address (2) Text recording the address number, or post office box number and street name where the business is located.
Telephone Number The telephone number of the business.
Telephone Number International Dialing Code The telephone number international dialing code of the business.
Territory Abbreviated Name Text recording the shortened name of the locally governed area which forms part of a centrally governed nation to identify where the business is located.
Territory Name Text recording the name of the locally governed area which forms part of a centrally governed nation to identify where the business is located.
Town Name Text recording the name of a city, town, township, village, borough, etc. where the business is located.
Trade Style Name Text recording the name which an organization trades under for commercial purposes although its registered legal name used for contracts and other formal situations may be another name.

Product Notes

The availability of certain scores delivered by this product may be limited due to a lack of sufficient company or industry specific data to perform the calculations.

The D&B Total Loss Predictor score will predict a business’s intent or willingness to not pay other commercial businesses (business to business dealings), which affects financial institutions and other industries that extend trade credit. The score calculation makes use of historical search patterns from a search database along with other high-risk identifiers and proprietary data to produce a score that can be used to discriminate between fraudulent and legitimate credit seeking payment behavior.

The following table is a list of possible values for the Reason Code business elements mentioned in the preceding table.

Commentary TextCode
Address identified as a consumer address26176
Address information on file differs from external sources26175
Number of retail Inquiries26182
Business information is not confirmed by available external sources26179
Some firmographic data differs from available external data sources26205
Dollar amount of suits, liens, or judgements26215
Evidence of negative trade26092
Higher risk industry based on delinquency rates for this industry26090
Higher risk industry based on risk rates for this industry26214
Higher risk region based on delinquency rate for this region26086
Limited or no enquiries26211
Limited time under present management control19812
No Payment Experiences reported26094
Limited number of payment experiences reported26153
Physical address has incorrect or missing information26210
Proportion of recent past due balances reported26209
Proportion of past due balances to total amount owing26173
Proportion of recent slow payment experiences reported26212
Proportion of retail enquiries26208
Proportion of slow payment balances reported26207
Proportion of slow payment experiences to total number of payment experiences reported26172
Recent slow payment reported26206
Reported high credit amount26204
Indications of Business Deterioration or high risk26394
Unable to confirm active operations26395
Operating Status - Out of Business1881
Indication of open bankruptcy26396
Self Requested Duns26398