DHL Selection API

openapi: 3.2.0
info:
  title: Dhl Selection API
  version: 26.10.30-74-fe9dc15580501f34951cc8ff7f032a067ea13a58
  contact:
    name: Technical Support
    email: it-csp@deutschepost.de
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  description: 'Operations tagged Selection across 2 of this provider''s published API definitions: dhl-deutsche-post-print-mailing-targeting-post-parcel-germany-openapi.yml, dhl-deutsche-post-print-mailing-targeting-post-parcel-germany-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api-eu.dhl.com/post/advertising/print-mailing
  description: Production environment
- url: https://api-uat.dhl.com/post/advertising/print-mailing
  description: Test environment
tags:
- name: Selection
  description: This authenticated and customer specific selection endpoints can be used to prepare a selection for further use (store, booking ...). All requests need authentication via JWT.
paths:
  /targeting/v1/customers/{customerId}/selections:
    get:
      tags:
      - Selection
      summary: List selection of a specific customer
      description: List the stored selections for a customer. Can only be accessed by valid token for that customerId.
      operationId: list
      parameters:
      - name: customerId
        in: path
        description: The customer id to identify the requested selections.
        required: true
        schema:
          type: integer
          format: int64
          description: The customer id to identify the requested selections.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserSelection'
    post:
      tags:
      - Selection
      summary: Create a new selection for a customer
      description: Saves a new selection for the customer and returns the id. Can only be accessed by valid token for that customerId.
      operationId: create_2
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SelectionRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSelection'
    servers:
    - url: https://api-eu.dhl.com/post/advertising/print-mailing
      description: Production environment
    - url: https://api-uat.dhl.com/post/advertising/print-mailing
      description: Test environment
  /targeting/v1/customers/{customerId}/selections/{selectionId}:
    get:
      tags:
      - Selection
      summary: Get a stored selection by the id for a specific customer
      description: Get a stored selection by id for a customer. Can only be accessed by valid token for that customerId.
      operationId: get
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: selectionId
        in: path
        required: true
        schema:
          type: string
      - name: recalculate
        in: query
        required: false
        schema:
          type: boolean
      responses:
        '404':
          description: No selection found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseRep'
              example:
                timestamp: '2021-02-10T12:34:06.203Z'
                status: 404
                correlationId: a5fe243a-05bc-4a55-ae03-02bc34d43f9a
                error: Not Found
                errors:
                - errorCode: DM_CO_0008
                  errorMessage: 'Ein Datensatz konnte nicht gefunden werden: 41d709d6-3a6-41e2-89d6-da51a4a07f96.'
                  arguments:
                  - 41d709d6-3a6-41e2-89d6-da51a4a07f96
                  fieldName: null
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaSelectionSummary'
    delete:
      tags:
      - Selection
      summary: Deletes a selection
      description: Deletes a selection and returns HTTP 200. Can only be accessed by valid token for that customerId.
      operationId: delete
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: selectionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '404':
          description: No selection found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseRep'
              example:
                timestamp: '2021-02-10T12:34:06.203Z'
                status: 404
                correlationId: a5fe243a-05bc-4a55-ae03-02bc34d43f9a
                error: Not Found
                errors:
                - errorCode: DM_CO_0008
                  errorMessage: 'Ein Datensatz konnte nicht gefunden werden: 41d709d6-3a6-41e2-89d6-da51a4a07f96.'
                  arguments:
                  - 41d709d6-3a6-41e2-89d6-da51a4a07f96
                  fieldName: null
        '200':
          description: Success
          content:
            application/json: {}
    patch:
      tags:
      - Selection
      summary: Update a selection
      description: Updates a selection and returns the id. Can only be accessed by valid token for that customerId.
      operationId: update
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: selectionId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SelectionRequest'
        required: true
      responses:
        '404':
          description: No selection found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseRep'
              example:
                timestamp: '2021-02-10T12:34:06.203Z'
                status: 404
                correlationId: a5fe243a-05bc-4a55-ae03-02bc34d43f9a
                error: Not Found
                errors:
                - errorCode: DM_CO_0008
                  errorMessage: 'Ein Datensatz konnte nicht gefunden werden: 41d709d6-3a6-41e2-89d6-da51a4a07f96.'
                  arguments:
                  - 41d709d6-3a6-41e2-89d6-da51a4a07f96
                  fieldName: null
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSelection'
    servers:
    - url: https://api-eu.dhl.com/post/advertising/print-mailing
      description: Production environment
    - url: https://api-uat.dhl.com/post/advertising/print-mailing
      description: Test environment
  /targeting/v1/customers/{customerId}/selections/{selectionId}/name:
    patch:
      tags:
      - Selection
      summary: Updates the name of a selection
      description: Updates the name of a selection and returns the id. Can only be accessed by valid token for that customerId.
      operationId: updateName
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: selectionId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: string
        required: true
      responses:
        '404':
          description: No selection found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseRep'
              example:
                timestamp: '2021-02-10T12:34:06.203Z'
                status: 404
                correlationId: a5fe243a-05bc-4a55-ae03-02bc34d43f9a
                error: Not Found
                errors:
                - errorCode: DM_CO_0008
                  errorMessage: 'Ein Datensatz konnte nicht gefunden werden: 41d709d6-3a6-41e2-89d6-da51a4a07f96.'
                  arguments:
                  - 41d709d6-3a6-41e2-89d6-da51a4a07f96
                  fieldName: null
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: string
                example: '{"name","my selection"}'
    servers:
    - url: https://api-eu.dhl.com/post/advertising/print-mailing
      description: Production environment
    - url: https://api-uat.dhl.com/post/advertising/print-mailing
      description: Test environment
  /targeting/v1/customers/{customerId}/selections/{selectionId}/packaging:
    get:
      tags:
      - Selection
      summary: Get information for packaging of the selection
      description: Request all information for packaging the selection (only for product POSTAKTUELL). Can only be accessed by valid token for that customerId.
      operationId: getPackagingInformation
      parameters:
      - name: selectionId
        in: path
        required: true
        schema:
          type: string
      - name: customerId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: packaging
        in: query
        required: false
        schema:
          type: string
          default: DELIVERY_BASE
          enum:
          - DELIVERY_DISTRICT
          - DELIVERY_BASE
      responses:
        '404':
          description: No selection found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseRep'
              example:
                timestamp: '2021-02-10T12:34:06.203Z'
                status: 404
                correlationId: a5fe243a-05bc-4a55-ae03-02bc34d43f9a
                error: Not Found
                errors:
                - errorCode: DM_CO_0008
                  errorMessage: 'Ein Datensatz konnte nicht gefunden werden: 41d709d6-3a6-41e2-89d6-da51a4a07f96.'
                  arguments:
                  - 41d709d6-3a6-41e2-89d6-da51a4a07f96
                  fieldName: null
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackagingSelectionSummary'
    servers:
    - url: https://api-eu.dhl.com/post/advertising/print-mailing
      description: Production environment
    - url: https://api-uat.dhl.com/post/advertising/print-mailing
      description: Test environment
  /targeting/v1/customers/{customerId}/selections/{selectionId}/dispatch-information:
    get:
      tags:
      - Selection
      summary: Request a summary about the information to dispatch the selection
      description: Request all information for future dispatching the selection. Can only be accessed by valid token for that customerId.
      operationId: getDispatchInformation_1
      parameters:
      - name: selectionId
        in: path
        required: true
        schema:
          type: string
      - name: customerId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '404':
          description: No selection found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseRep'
              example:
                timestamp: '2021-02-10T12:34:06.203Z'
                status: 404
                correlationId: a5fe243a-05bc-4a55-ae03-02bc34d43f9a
                error: Not Found
                errors:
                - errorCode: DM_CO_0008
                  errorMessage: 'Ein Datensatz konnte nicht gefunden werden: 41d709d6-3a6-41e2-89d6-da51a4a07f96.'
                  arguments:
                  - 41d709d6-3a6-41e2-89d6-da51a4a07f96
                  fieldName: null
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisPaApiRep'
    servers:
    - url: https://api-eu.dhl.com/post/advertising/print-mailing
      description: Production environment
    - url: https://api-uat.dhl.com/post/advertising/print-mailing
      description: Test environment
components:
  schemas:
    DeliveryBasePackaging:
      allOf:
      - $ref: '#/components/schemas/AbstractPackaging'
      - type: object
        properties:
          fullDeliveryBase:
            type: boolean
    HHCount:
      type: object
      properties:
        quantityTariffZoneA:
          type: integer
          format: int32
          description: Households in tariffzone A
          example: 178
        quantityTariffZoneB:
          type: integer
          format: int32
          description: Households in tariffzone B
          example: 289
        neighbourhood:
          type: string
          description: Name of the neighbourhood
          example: Gronau
        postalCode:
          type: string
          description: Zip of the neighbourhood
          example: 53113
        city:
          type: string
          description: Name of the city
          example: Bonn
    MetaSummary:
      type: object
      description: Meta information of a selection
      properties:
        id:
          type: string
          example: f36ac95d-d412-43ad-947b-29f2e3ddb249
        customerId:
          type: string
          example: 1234
        name:
          type: string
          example: MySelection
        orderedUntil:
          type: string
          format: date
          description: If the selection is part of an active order it is locked against changes and deletion until this date. Null if the selection is not used by an order.
          example: '2023-12-24'
        locked:
          type: boolean
          description: True if the selection is currently locked because it is part of an active order. False if not locked.
          example: true
        type:
          type: string
          enum:
          - POSTAL_CODE
          - DELIVERY_DISTRICT
          - NEIGHBOURHOOD
          example: POSTAL_CODE
        productType:
          type: string
          enum:
          - POSTAKTUELL_DAILY_MAIL
          - POSTAKTUELL_ALL
          - POSTAKTUELL_ANY_AND_ALL_HOUSEHOLDS
          - POSTWURF_SPEZIAL
          example: POSTAKTUELL_DAILY_MAIL
        numberOfAreas:
          type: integer
          format: int32
          example: 2
        netQuantity:
          type: integer
          format: int32
          description: Number of households netto.
          example: 1179
        bruttoQuantity:
          type: integer
          format: int32
          description: Number of households brutto. Authority ROLE_DIS_POSTAKTUELL_ANY_AND_ALL_HOUSEHOLDS is needed to see this value.
          example: 1203
        quantity:
          type: integer
          format: int32
          example: 826
        itemWeightInGram:
          type: integer
          format: int32
          example: 20
        itemsPerPackage:
          type: integer
          format: int32
          example: 500
        tolerance:
          type: integer
          format: int32
          example: 0
        roundOff:
          type: integer
          format: int32
          example: 20
        dataVersion:
          type: string
          example: '2021-08-18T09:01:24.665844'
        filters:
          type: array
          items:
            $ref: '#/components/schemas/PotentialFilter'
        filterCosts:
          type: integer
          format: int32
    PackagingSelectionSummary:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/MetaSummary'
        packagings:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/DeliveryBasePackaging'
            - $ref: '#/components/schemas/DeliveryDistrictPackaging'
          uniqueItems: true
    AbstractPackaging:
      type: object
      anyOf:
      - $ref: '#/components/schemas/DeliveryBasePackaging'
      - $ref: '#/components/schemas/DeliveryDistrictPackaging'
      description: Packaging object
      properties:
        deliveryBaseName:
          type: string
          description: Name of the delivery base
          example: Bonn 102
        deliveryBasePostalCode:
          type: string
          description: Zip of the delivery base
          example: 53113
        deliveryBaseOrgOz:
          type: string
          description: OrgOZ of the delivery base
          example: 111122223333
        quantityTariffZoneA:
          type: integer
          format: int32
          description: Households in tariffzone A of the delivery base
          example: 15000
        quantityTariffZoneB:
          type: integer
          format: int32
          description: Households in tariffzone B of the delivery base
          example: 15000
        roundedTotal:
          type: integer
          format: int32
        packages:
          type: integer
          format: int32
        lastPackageQuantity:
          type: integer
          format: int32
        neighbourhoods:
          type: array
          description: List of neighbourhoods in the delivery base
          items:
            $ref: '#/components/schemas/HHCount'
    PotentialFilter:
      type: object
      description: Filter for PWS
      properties:
        id:
          type: string
          example: k_kaufkr_kombi
        options:
          type: array
          example:
          - '4'
          items:
            type: string
    DeliveryDistrictPackaging:
      allOf:
      - $ref: '#/components/schemas/AbstractPackaging'
      - type: object
        properties:
          deliveryDistrictName:
            type: string
          fullDeliveryDistrict:
            type: boolean
    DisPaApiRep:
      type: object
      description: Response body of the dispatch-information
      properties:
        numberItemsTariffZoneA:
          type: integer
          format: int32
          example: 123
        numberItemsTariffZoneB:
          type: integer
          format: int32
          example: 123
        itemWeightInGram:
          type: integer
          format: int32
          example: 20
        productType:
          type: string
          enum:
          - POSTAKTUELL_DAILY_MAIL
          - POSTAKTUELL_ALL
          - POSTAKTUELL_ANY_AND_ALL_HOUSEHOLDS
          - POSTWURF_SPEZIAL
          example: POSTAKTUELL_DAILY_MAIL
        deliveryDistrictSelection:
          type: boolean
          example: false
        inductionDate:
          type: string
          example: '2021-07-01T07:43:56.001Z'
    MetaSelectionSummary:
      type: object
      description: Response describing a selection
      properties:
        meta:
          $ref: '#/components/schemas/MetaSummary'
        areaCodes:
          type: array
          example:
          - '48231'
          - '47877'
          items:
            type: string
          uniqueItems: true
        areaCodeHouseholdDifferences:
          type: array
          example:
          - areacode: '48231'
            households: 47877
          items:
            $ref: '#/components/schemas/AreaCodeInformation'
          uniqueItems: true
    ErrorRep:
      type: object
      properties:
        errorCode:
          type: string
        errorMessage:
          type: string
        arguments:
          type: array
          items: {}
        fieldName:
          type: string
      xml:
        name: error
    SelectionRequest:
      type: object
      description: Request for a new Selection
      properties:
        name:
          type: string
          example: my selection
          maxLength: 50
          pattern: ^.{0,50}$
        detailLevel:
          type: string
          enum:
          - POSTAL_CODE
          example: POSTAL_CODE
        areaCodes:
          type: array
          example:
          - '48231'
          items:
            type: string
            pattern: ^[0-9]+(-[0-9]{2})?$
          uniqueItems: true
        product:
          type: string
          enum:
          - POSTAKTUELL_DAILY_MAIL
          - POSTAKTUELL_ALL
          - POSTAKTUELL_ANY_AND_ALL_HOUSEHOLDS
          - POSTWURF_SPEZIAL
          example: POSTAKTUELL_DAILY_MAIL
        filters:
          type: array
          items:
            $ref: '#/components/schemas/PotentialFilter'
        itemWeightInGram:
          type: integer
          format: int32
          example: 20
    AreaCodeInformation:
      type: object
      properties:
        areaCode:
          type: string
        households:
          type: integer
          format: int32
    UserSelection:
      type: object
      description: Selection of a user.
      properties:
        id:
          type: string
          description: Id of the Selection
          example: aaaa11aa-aa11-aa11-aa11-aaaa11aaaa11
        name:
          type: string
          description: Name of the Selection
          example: My Selection 1
        orderedUntil:
          type: string
          format: date
          description: If the selection is part of an active order it is locked against changes and deletion until this date. Null if the selection is not used by an order.
          example: '2023-12-24'
        locked:
          type: boolean
          description: True if the selection is currently locked because it is part of an active order. False if not locked.
          example: true
    ErrorResponseRep:
      type: object
      properties:
        timestamp:
          type: string
        status:
          type: integer
          format: int32
        correlationId:
          type: string
        error:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorRep'
      xml:
        name: errorResponse
x-refined-from:
- dhl-deutsche-post-print-mailing-targeting-post-parcel-germany-openapi.yml
- dhl-deutsche-post-print-mailing-targeting-post-parcel-germany-openapi.yml