D&B Direct+ API

openapi: 3.0.3
info:
  title: D&B Direct+ API
  description: >-
    D&B Direct+ is Dun & Bradstreet's RESTful API platform that exposes the
    D&B Data Cloud — more than 500 million companies worldwide — for identity
    resolution, search, enrichment, multi-process (match plus enrich), batch
    processing, change monitoring, and historical research. All endpoints
    return JSON, are versioned in the URI path, and require an OAuth 2.0
    bearer token obtained from the /v3/token endpoint via client-credentials
    grant. This profile is an OpenAPI sketch of the public surface based on
    Dun & Bradstreet's published Direct+ documentation; the canonical
    operation definitions live behind the gated developer portal at
    https://directplus.documentation.dnb.com/.
  version: '3.0'
  contact:
    name: D&B Direct+ Support
    url: https://service.dnb.com/
  termsOfService: https://www.dnb.com/utility-pages/terms-of-use.html
  license:
    name: Proprietary
    url: https://www.dnb.com/utility-pages/terms-of-use.html
servers:
  - url: https://plus.dnb.com
    description: Production
tags:
  - name: Authentication
    description: OAuth 2.0 token issuance for Direct+.
  - name: Identity Resolution
    description: Match an input record to a D-U-N-S Number.
  - name: Search
    description: Find companies, principals, and related entities.
  - name: Enrich
    description: Retrieve Data Blocks for a known D-U-N-S Number.
  - name: Multi-Process
    description: Combined match plus enrich in a single call.
  - name: Data File
    description: Asynchronous batch file submission, status, and download.
  - name: Monitoring
    description: Subscribe to and consume change notifications on a portfolio.
  - name: Research
    description: Retrieve historical responses for audit and reconciliation.
paths:
  /v3/token:
    post:
      tags:
        - Authentication
      summary: Generate Direct+ Access Token
      description: >-
        Exchange Direct+ API credentials for an OAuth 2.0 bearer access token
        using the client-credentials grant. The returned token is included as
        a Bearer authorization header on all subsequent Direct+ calls.
      operationId: generateAccessToken
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: Access token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/match/cleanseMatch:
    get:
      tags:
        - Identity Resolution
      summary: Match Candidate To D-U-N-S Number
      description: >-
        Submit a candidate business record (name, address, registration
        number, phone, email) and receive a ranked list of D-U-N-S Number
        matches with match-grade, confidence-code, and quality indicators
        suitable for auto-acceptance or manual review.
      operationId: cleanseMatch
      security:
        - bearerAuth: []
      parameters:
        - name: name
          in: query
          required: true
          schema: { type: string }
          description: Business name as supplied by the caller.
        - name: countryISOAlpha2Code
          in: query
          required: true
          schema: { type: string, minLength: 2, maxLength: 2 }
          description: ISO 3166-1 alpha-2 country code.
        - name: streetAddressLine1
          in: query
          schema: { type: string }
        - name: addressLocality
          in: query
          schema: { type: string }
        - name: addressRegion
          in: query
          schema: { type: string }
        - name: postalCode
          in: query
          schema: { type: string }
        - name: telephoneNumber
          in: query
          schema: { type: string }
        - name: registrationNumber
          in: query
          schema: { type: string }
        - name: candidateMaximumQuantity
          in: query
          schema: { type: integer, minimum: 1, maximum: 50, default: 9 }
        - name: confidenceLowerLevelThresholdValue
          in: query
          schema: { type: integer, minimum: 1, maximum: 10 }
      responses:
        '200':
          description: Ranked match candidates returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/search/criteria:
    get:
      tags:
        - Search
      summary: Search Companies By Criteria
      description: >-
        Find companies matching free-form criteria such as name, address,
        registration number, industry, or contact. Returns a paginated list
        of candidate records intended for browse-and-pick workflows rather
        than authoritative match.
      operationId: searchCompaniesByCriteria
      security:
        - bearerAuth: []
      parameters:
        - name: searchTerm
          in: query
          schema: { type: string }
        - name: countryISOAlpha2Code
          in: query
          schema: { type: string }
        - name: pageNumber
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
        - name: pageSize
          in: query
          schema: { type: integer, minimum: 1, maximum: 50, default: 50 }
      responses:
        '200':
          description: Search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/search/contact:
    get:
      tags:
        - Search
      summary: Search Contacts By Criteria
      description: >-
        Find named principals or contacts (executives, beneficial owners,
        decision-makers) matching the supplied criteria, returning a
        paginated candidate list.
      operationId: searchContacts
      security:
        - bearerAuth: []
      parameters:
        - name: searchTerm
          in: query
          schema: { type: string }
        - name: countryISOAlpha2Code
          in: query
          schema: { type: string }
        - name: pageSize
          in: query
          schema: { type: integer, minimum: 1, maximum: 50, default: 50 }
      responses:
        '200':
          description: Contact search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactSearchResponse'
  /v1/data/duns/{duns}:
    get:
      tags:
        - Enrich
      summary: Retrieve Data Blocks For D-U-N-S
      description: >-
        Retrieve one or more Data Blocks for a given D-U-N-S Number. The
        caller specifies which blocks (Company Information, Principals &
        Contacts, Hierarchy & Connections, Financial Strength, Risk &
        Compliance, Beneficial Ownership, ESG, etc.) to include via the
        blockIDs query parameter. Each block is independently versioned.
      operationId: getDataBlocksByDuns
      security:
        - bearerAuth: []
      parameters:
        - name: duns
          in: path
          required: true
          schema:
            type: string
            pattern: '^[0-9]{9}$'
          description: Nine-digit D-U-N-S Number.
        - name: blockIDs
          in: query
          required: true
          schema:
            type: string
          description: >-
            Comma-separated list of block IDs with version (e.g.
            companyinfo_L2_v1,principalscontacts_L1_v2).
        - name: tradeUp
          in: query
          schema: { type: string, enum: [hq] }
      responses:
        '200':
          description: Requested data blocks for the D-U-N-S Number.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/multiProcess:
    post:
      tags:
        - Multi-Process
      summary: Match Plus Enrich In One Call
      description: >-
        Combine Identity Resolution and Enrich in a single request: supply
        a candidate input record and the desired data blocks; Direct+ returns
        the resolved D-U-N-S match together with all requested enrichment
        payloads.
      operationId: multiProcessMatchAndEnrich
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultiProcessRequest'
      responses:
        '200':
          description: Resolved match plus enrichment payloads.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiProcessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/file:
    post:
      tags:
        - Data File
      summary: Submit Batch Data File
      description: >-
        Submit a batch input file for asynchronous match and enrichment.
        Returns a fileID the caller polls until processing is complete.
      operationId: submitBatchFile
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/BatchFileSubmission'
      responses:
        '202':
          description: File accepted for processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchSubmissionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/file/{fileId}/status:
    get:
      tags:
        - Data File
      summary: Get Batch File Status
      description: >-
        Poll the processing status of a previously submitted batch file.
        Returns a state of PENDING, PROCESSING, COMPLETED, or FAILED along
        with progress counters.
      operationId: getBatchFileStatus
      security:
        - bearerAuth: []
      parameters:
        - name: fileId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Batch file status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/file/{fileId}/download:
    get:
      tags:
        - Data File
      summary: Download Batch File Results
      description: >-
        Download the matched and enriched output file once status is
        COMPLETED. The response is an octet-stream containing the result
        file in the originally requested format.
      operationId: downloadBatchFileResults
      security:
        - bearerAuth: []
      parameters:
        - name: fileId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Batch result file.
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/monitoring/registrations:
    post:
      tags:
        - Monitoring
      summary: Create Monitoring Registration
      description: >-
        Register a portfolio of D-U-N-S Numbers for change monitoring. The
        registration declares which data blocks to monitor and how
        notifications should be delivered.
      operationId: createMonitoringRegistration
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitoringRegistrationRequest'
      responses:
        '201':
          description: Monitoring registration created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitoringRegistrationResponse'
  /v1/monitoring/registrations/{registrationReference}/duns:
    post:
      tags:
        - Monitoring
      summary: Add D-U-N-S To Registration
      description: >-
        Add one or more D-U-N-S Numbers to an existing monitoring
        registration's portfolio.
      operationId: addDunsToRegistration
      security:
        - bearerAuth: []
      parameters:
        - name: registrationReference
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PortfolioMembershipRequest'
      responses:
        '200':
          description: Portfolio updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortfolioMembershipResponse'
    delete:
      tags:
        - Monitoring
      summary: Remove D-U-N-S From Registration
      description: >-
        Remove one or more D-U-N-S Numbers from a monitoring registration's
        portfolio.
      operationId: removeDunsFromRegistration
      security:
        - bearerAuth: []
      parameters:
        - name: registrationReference
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PortfolioMembershipRequest'
      responses:
        '200':
          description: Portfolio updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortfolioMembershipResponse'
  /v1/monitoring/registrations/{registrationReference}/notifications:
    get:
      tags:
        - Monitoring
      summary: Pull Monitoring Notifications
      description: >-
        Pull pending change notifications for a monitoring registration.
        Each notification describes the D-U-N-S Number affected, the block
        that changed, the previous and new values, and the change timestamp.
      operationId: pullMonitoringNotifications
      security:
        - bearerAuth: []
      parameters:
        - name: registrationReference
          in: path
          required: true
          schema: { type: string }
        - name: maximumQuantity
          in: query
          schema: { type: integer, default: 100, maximum: 1000 }
      responses:
        '200':
          description: Notifications package.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitoringNotificationsResponse'
  /v2/audit/duns/{duns}:
    get:
      tags:
        - Research
      summary: Retrieve Historical Audit Record
      description: >-
        Retrieve a historical Direct+ response previously returned for a
        D-U-N-S Number, supporting audit, dispute, and reconciliation use
        cases.
      operationId: getAuditRecord
      security:
        - bearerAuth: []
      parameters:
        - name: duns
          in: path
          required: true
          schema:
            type: string
            pattern: '^[0-9]{9}$'
        - name: transactionTimestamp
          in: query
          required: true
          schema: { type: string, format: date-time }
      responses:
        '200':
          description: Historical record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditResponse'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    basicAuth:
      type: http
      scheme: basic
  responses:
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: Resource not found for the supplied identifier.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
  schemas:
    TokenRequest:
      type: object
      required: [grant_type]
      properties:
        grant_type:
          type: string
          enum: [client_credentials]
    TokenResponse:
      type: object
      properties:
        access_token: { type: string }
        token_type: { type: string, example: Bearer }
        expirationDateTime: { type: string, format: date-time }
    MatchCandidate:
      type: object
      properties:
        displaySequence: { type: integer }
        matchQualityInformation:
          type: object
          properties:
            confidenceCode: { type: integer }
            matchGrade: { type: string }
            matchDataProfile: { type: string }
        organization:
          $ref: '#/components/schemas/OrganizationSummary'
    MatchResponse:
      type: object
      properties:
        transactionDetail:
          $ref: '#/components/schemas/TransactionDetail'
        inquiryDetail:
          type: object
        matchCandidates:
          type: array
          items: { $ref: '#/components/schemas/MatchCandidate' }
    OrganizationSummary:
      type: object
      properties:
        duns: { type: string, pattern: '^[0-9]{9}$' }
        primaryName: { type: string }
        primaryAddress:
          $ref: '#/components/schemas/Address'
        countryISOAlpha2Code: { type: string }
        telephone:
          type: array
          items: { type: object, properties: { telephoneNumber: { type: string } } }
        registrationNumbers:
          type: array
          items: { type: object, properties: { registrationNumber: { type: string }, typeDescription: { type: string } } }
    Address:
      type: object
      properties:
        streetAddress:
          type: object
          properties:
            line1: { type: string }
            line2: { type: string }
        addressLocality: { type: object, properties: { name: { type: string } } }
        addressRegion: { type: object, properties: { name: { type: string }, abbreviatedName: { type: string } } }
        postalCode: { type: string }
        addressCountry: { type: object, properties: { isoAlpha2Code: { type: string } } }
    SearchResponse:
      type: object
      properties:
        transactionDetail: { $ref: '#/components/schemas/TransactionDetail' }
        candidatesReturnedQuantity: { type: integer }
        candidatesMatchedQuantity: { type: integer }
        searchCandidates:
          type: array
          items:
            type: object
            properties:
              organization: { $ref: '#/components/schemas/OrganizationSummary' }
    ContactSearchResponse:
      type: object
      properties:
        transactionDetail: { $ref: '#/components/schemas/TransactionDetail' }
        candidatesReturnedQuantity: { type: integer }
        searchCandidates:
          type: array
          items:
            type: object
            properties:
              contact:
                type: object
                properties:
                  fullName: { type: string }
                  jobTitles:
                    type: array
                    items: { type: object, properties: { title: { type: string } } }
              organization: { $ref: '#/components/schemas/OrganizationSummary' }
    EnrichResponse:
      type: object
      properties:
        transactionDetail: { $ref: '#/components/schemas/TransactionDetail' }
        inquiryDetail: { type: object }
        organization:
          type: object
          properties:
            duns: { type: string }
            primaryName: { type: string }
            primaryAddress: { $ref: '#/components/schemas/Address' }
            registrationNumbers:
              type: array
              items: { type: object }
            corporateLinkage: { type: object }
            financials:
              type: array
              items: { type: object }
            principals:
              type: array
              items: { type: object }
            beneficialOwnership: { type: object }
            riskAssessment: { type: object }
    MultiProcessRequest:
      type: object
      required: [inquiryDetail, blockIDs]
      properties:
        inquiryDetail:
          type: object
          properties:
            name: { type: string }
            countryISOAlpha2Code: { type: string }
            address: { $ref: '#/components/schemas/Address' }
        blockIDs:
          type: array
          items: { type: string }
    MultiProcessResponse:
      type: object
      properties:
        transactionDetail: { $ref: '#/components/schemas/TransactionDetail' }
        matchCandidates:
          type: array
          items: { $ref: '#/components/schemas/MatchCandidate' }
        organization:
          type: object
          description: Resolved enrichment payload for the top-ranked match.
    BatchFileSubmission:
      type: object
      properties:
        file:
          type: string
          format: binary
        processId: { type: string, description: 'Direct+ process identifier (match, enrich, etc).' }
        productId: { type: string }
    BatchSubmissionResponse:
      type: object
      properties:
        fileId: { type: string }
        submissionTimestamp: { type: string, format: date-time }
        status: { type: string, enum: [PENDING] }
    BatchStatusResponse:
      type: object
      properties:
        fileId: { type: string }
        status: { type: string, enum: [PENDING, PROCESSING, COMPLETED, FAILED] }
        processedRecordCount: { type: integer }
        totalRecordCount: { type: integer }
    MonitoringRegistrationRequest:
      type: object
      required: [registrationReference]
      properties:
        registrationReference: { type: string }
        description: { type: string }
        blockIDs:
          type: array
          items: { type: string }
        deliveryMethod: { type: string, enum: [SFTP, API_PULL] }
    MonitoringRegistrationResponse:
      type: object
      properties:
        registrationReference: { type: string }
        status: { type: string }
        createdTimestamp: { type: string, format: date-time }
    PortfolioMembershipRequest:
      type: object
      required: [dunsList]
      properties:
        dunsList:
          type: array
          items: { type: string, pattern: '^[0-9]{9}$' }
    PortfolioMembershipResponse:
      type: object
      properties:
        addedQuantity: { type: integer }
        removedQuantity: { type: integer }
        rejectedDuns:
          type: array
          items: { type: object, properties: { duns: { type: string }, reason: { type: string } } }
    MonitoringNotificationsResponse:
      type: object
      properties:
        notifications:
          type: array
          items:
            type: object
            properties:
              duns: { type: string }
              changeTimestamp: { type: string, format: date-time }
              blockID: { type: string }
              elementId: { type: string }
              previousValue: {}
              currentValue: {}
    AuditResponse:
      type: object
      properties:
        duns: { type: string }
        transactionTimestamp: { type: string, format: date-time }
        originalResponse: { type: object }
    TransactionDetail:
      type: object
      properties:
        transactionID: { type: string }
        transactionTimestamp: { type: string, format: date-time }
        inLanguage: { type: string }
        serviceVersion: { type: string }
    Error:
      type: object
      properties:
        transactionDetail: { $ref: '#/components/schemas/TransactionDetail' }
        error:
          type: object
          properties:
            errorMessage: { type: string }
            errorCode: { type: string }
            errorDetails:
              type: array
              items: { type: object }