openapi: 3.1.0
info:
  version: 1.0.0
  title: Consumer And Misc
  description: |
    # Introduction

     Endpoints to order Consumer Reports. In order to order a Consumer
     Report, sufficient information to uniquely identify the Consumer (search
     criteria) must be provided to filter potential results down to one record.
     When one record has been found, the returned object will be the Consumer
     Report. Currently only piloting with German Consumers.
tags:
  - name: Authentication
  - name: Consumers
    description: Update this description.
servers:
  - url: https://connect.sandbox.creditsafe.com/v1
    description: Sandbox server
  - url: https://connect.creditsafe.com/v1
    description: Production server
paths:
  /authenticate:
    post:
      operationId: authenticate
      summary: Authenticate
      security: []
      tags:
        - Authentication
      description: |
        Supply username and password to generate Authentication Token.
          
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectAuthenticationAuthRequest'
        required: false
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectAuthenticationAuthResponse'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectErrorResponsesInvalidToken'
  /consumers:
    get:
      tags:
        - Consumers
      description: >-
        Consumer Search and Report endpoint. When sufficient information has
        been provided to filter potential Consumer results down to one record
        then the Consumer Report will be returned.
      operationId: consumerReport
      summary: Consumer Report
      parameters:
        - name: countries
          in: query
          example: DE
          description: ISO-2 country code
          required: true
          schema:
            $ref: '#/components/schemas/CreditsafeGlobalDataCountryCode'
        - name: language
          in: query
          description: ''
          schema:
            type: string
            nullable: true
            default: EN
            maxLength: 2
            minLength: 2
        - name: firstName
          in: query
          description: Consumer's First Name
          schema:
            type: string
          required: true
        - name: lastName
          in: query
          description: Consumer's Last Name
          schema:
            type: string
          required: true
        - name: street
          in: query
          description: Address part identifier - Street of the Consumer
          schema:
            type: string
          required: true
        - name: houseNo
          in: query
          description: Address part identifier - House/Building Number of the Consumer
          schema:
            type: string
          required: true
        - name: city
          in: query
          description: Address part identifier - City of the Consumer
          schema:
            type: string
          required: true
        - name: postCode
          in: query
          description: Address part identifier - Postcode/Zip Code of the Consumer
          schema:
            type: string
          required: true
        - name: dateOfBirth
          in: query
          schema:
            type: string
            format: date-time
            nullable: true
        - name: customData
          in: query
          example: de_reason_code::ER
          schema:
            type: string
            nullable: true
        - name: callRef
          in: query
          description: >-
            This parameter allows users to assign a unique identifier to their
            API queries. By using a callRef, it facilitates easier tracking and
            logging within Connect. If you provide a callRef, the Connect team
            can later retrieve and identify the specific requests associated
            with that identifier, enabling detailed tracing of interactions.
          schema:
            type: string
            nullable: true
            default: null
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalSize:
                    type: integer
                    format: int32
                  consumers:
                    type: array
                    items:
                      $ref: >-
                        #/components/schemas/CreditsafeGlobalDataReportsConsumerConsumerReport
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectErrorResponsesBadRequest'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectErrorResponsesInvalidToken'
  /consumers/searchcriteria:
    get:
      tags:
        - Consumers
      description: >-
        Returns country specific fields that can be used to search for a
        Consumer.
      operationId: consumerSearchCriteria
      summary: Consumer Search Criteria
      parameters:
        - name: countries
          required: true
          in: query
          description: Comma-separated list of ISO-2 country codes
          schema:
            type: string
        - name: callRef
          in: query
          description: >-
            This parameter allows users to assign a unique identifier to their
            API queries. By using a callRef, it facilitates easier tracking and
            logging within Connect. If you provide a callRef, the Connect team
            can later retrieve and identify the specific requests associated
            with that identifier, enabling detailed tracing of interactions.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: >-
                        #/components/schemas/CreditsafeGlobalDataReportsConsumerCriteriaSet
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectErrorResponsesBadRequest'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectErrorResponsesInvalidToken'
components:
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        This API requires authentication for access to protected endpoints.
        Authentication is performed by providing a valid JWT token in the
        `Authorization` header of each request.
  schemas:
    ConnectAuthenticationAuthRequest:
      type: object
      properties:
        username:
          type: string
          description: Credentials assigned upon sign up
          example: username@domain.com
        password:
          type: string
          example: ^1gHySRA56aj>tf421o
    ConnectAuthenticationAuthResponse:
      type: object
      properties:
        token:
          type: string
          description: Authentication Token
          example: >-
            eyJhbGciOiJSUzI1NiIsImtpZCI6ImRodTNnNkFtTG5QQXVpOEJSMUFEVnp5ZHBnZyIsInR5cCI6IkpXVCIsIng1dCI6ImRodTNnNkFtTG5QQXVpOEJSMUFEVnp5ZHBnZyJ9.eyJuYmYiOjE1OTU0MTYyMDksImV4cCI6MTU5NTQxOTgwOSwiaXNzIjoiaHR0cHM6Ly9teWxvZ2luLnRlc3QuY3JlZGl0c2FmZS5jb20iLCJhdWQiOlsiaHR0cHM6Ly9teWxvZ2luLnRlc3QuY3JlZGl0c2FmZS5jb20vcmVzb3VyY2VzIiwiY29ubmVjdF9hcGkiLCJ1Ym9fYXBpX2dhdGV3YXkiXSwiY2xpZW50X2lkIjoiY29ubmVjdC5hcGkuY2xpZW50Iiwic3ViIjoiMTAxNTIwMjg1IiwiYXV0aF90aW1lIjoxNTk1NDE2MjA5LCJpZHAiOiJsb2NhbCIsInVzZXJuYW1lIjoiQ29ubmVjdHUxIiwiZW1haWwiOiJDb25uZWN0MUBnbWFpbC5jb20iLCJjdXN0b21lcklkIjoiMTAxNzY0NDA1IiwiY291bnRyeSI6IkMwIiwidXNlclJvbGUiOiJDcm1BZG1pblBsdXMiLCJzYl9jb3VudHJ5IjoiVVMiLCJzY29wZSI6WyJjb25uZWN0X2FwaSIsInVib19hcGlfZ2F0ZXdheSJdLCJhbXIiOlsicHdkIl19.p8kPAlKNB9iWEKiQbfbRXBoLQuBG7NuEDN__A8AQ55CL-gcIwkS1717Af1f9W0uifwIQ6HAZQR_x191LVkvuWD94Zw8zLzzr1ioUIhQny_zYuAS3G6EFNaTHh_mvOQ9XVi1FyuIy6YYcYcNLNZurFuITF2w5LuX4YQBjQy3rhEAdRoKcUKbtCClMFaH2dV35jiX2d7BqyhtJ8GeZyJ6yfMfdzznqxlJ4Osf5aasKUy8RYKEpjU2pkCURojoy5_oviGs8X4U9mJWcuajmPF3i5DHkqbhq1Mp0UZrDyoq_0BDStV5xqRgq6aOY8mc45kX7cwY3O2hPeGE7Ak8YtKFbA
    ConnectErrorResponsesInvalidToken:
      type: object
      properties:
        error:
          type: string
      description: >-
        401 - Authorization Token has either expired or is not a valid Connect
        Token
    CreditsafeGlobalDataCountryCode:
      description: Country where the company is registered.
      enum:
        - AF
        - AX
        - AL
        - DZ
        - AS
        - AD
        - AO
        - AI
        - AQ
        - AG
        - AR
        - AM
        - AW
        - AU
        - AT
        - AZ
        - BS
        - BH
        - BD
        - BB
        - BY
        - BE
        - BZ
        - BJ
        - BM
        - BT
        - BO
        - BA
        - BW
        - BV
        - BR
        - IO
        - BN
        - BG
        - BF
        - BI
        - KH
        - CM
        - CA
        - CV
        - KY
        - CF
        - TD
        - CL
        - CN
        - CX
        - CC
        - CO
        - KM
        - CG
        - CD
        - CK
        - CR
        - CI
        - HR
        - CU
        - CY
        - CZ
        - DK
        - DJ
        - DM
        - DO
        - EC
        - EG
        - SV
        - GQ
        - ER
        - EE
        - ET
        - FK
        - FO
        - FJ
        - FI
        - FR
        - GF
        - PF
        - TF
        - GA
        - GM
        - GE
        - DE
        - GH
        - GI
        - GR
        - GL
        - GD
        - GP
        - GU
        - GT
        - GG
        - GN
        - GW
        - GY
        - HT
        - HM
        - HN
        - HK
        - HU
        - IS
        - IN
        - ID
        - IR
        - IQ
        - IE
        - IM
        - IT
        - JM
        - JP
        - JE
        - JO
        - KZ
        - KE
        - KI
        - KP
        - KR
        - KW
        - KG
        - LA
        - LV
        - LB
        - LS
        - LR
        - LY
        - LI
        - LT
        - LU
        - MO
        - MK
        - MG
        - MW
        - MY
        - MV
        - ML
        - MT
        - MH
        - MQ
        - MR
        - MU
        - YT
        - MX
        - FM
        - MD
        - ME
        - MS
        - MA
        - MZ
        - MM
        - NA
        - NR
        - NP
        - NL
        - AN
        - NC
        - NZ
        - NI
        - NE
        - NG
        - NU
        - NF
        - MP
        - 'NO'
        - OM
        - PK
        - PW
        - PS
        - PA
        - PG
        - PY
        - PE
        - PH
        - PN
        - PL
        - PT
        - PR
        - QA
        - RE
        - RO
        - RU
        - RW
        - BL
        - SH
        - KN
        - LC
        - MF
        - PM
        - VC
        - WS
        - ST
        - SA
        - SN
        - RS
        - SC
        - SL
        - SG
        - SK
        - SI
        - SB
        - SO
        - ZA
        - GS
        - ES
        - LK
        - SD
        - SR
        - SJ
        - SZ
        - SE
        - CH
        - SY
        - TW
        - TJ
        - TZ
        - TH
        - TL
        - TG
        - TK
        - TO
        - TT
        - TN
        - TR
        - TM
        - TC
        - TV
        - UG
        - UA
        - AE
        - GB
        - US
        - UM
        - UY
        - UZ
        - VU
        - VA
        - VE
        - VN
        - VG
        - VI
        - WF
        - EH
        - YE
        - ZM
        - ZW
        - XK
        - SS
        - SX
        - CW
        - BQ
        - WW
        - PLC
      type: string
    CreditsafeGlobalDataReportsGender:
      enum:
        - Unknown
        - Male
        - Female
        - NotApplicable
      type: string
    CreditsafeGlobalDataAddressData:
      type: object
      properties:
        type:
          type: string
          description: >-
            Address type description. Examples - "Registered Office", "Trading
            Address", "Postal Address", "Service Address" etc.
        simpleValue:
          type: string
          description: >-
            (Optionally populated) Registered address of the company. Whole
            string address if Creditsafe is unable to accurately assign values
            to specific address fields, or when specific local address formats
            need to be observed.
        street:
          type: string
          description: >-
            Street portion of the address line. Can also, optionally contain,
            the house number alongside the street.
        houseNumber:
          type: string
          description: House number portion of the address line.
        additionToAddress:
          type: string
          description: >-
            Additional details for a specified address, such as a PO Box number,
            or a unit number at the specified address location.
        city:
          type: string
          description: City portion of the address line.
        postalCode:
          type: string
          description: Postal code portion of the address line.
        province:
          type: string
          description: Province portion of the address line.
        region:
          type: string
          description: >-
            May contain the geographical region, for example "South-East" or a
            territorial division.
        telephone:
          type: string
          description: Registered telephone number.
        directMarketingOptOut:
          type: boolean
          nullable: true
          description: >-
            Boolean [true/false]. Where set to true, the subject has "opted out"
            via a central register, and they must not be contacted for
            commercial marketing purposes.
        directMarketingOptIn:
          type: boolean
          nullable: true
        country:
          $ref: '#/components/schemas/CreditsafeGlobalDataCountryCode'
    CreditsafeGlobalDataReportsAdditionalData:
      type: object
      description: A free-flowing section, containing country specific elements.
    CreditsafeGlobalDataReportsConsumerConsumerInformationAdditionalData:
      allOf:
        - $ref: '#/components/schemas/CreditsafeGlobalDataReportsAdditionalData'
        - type: object
    CreditsafeGlobalDataReportsConsumerConsumerInformation:
      type: object
      properties:
        name:
          type: string
        firstName:
          type: string
        surname:
          type: string
        age:
          type: integer
          format: int32
          nullable: true
        dateOfBirth:
          type: string
          format: date-time
          nullable: true
        gender:
          $ref: '#/components/schemas/CreditsafeGlobalDataReportsGender'
        consumerID:
          type: string
        address:
          $ref: '#/components/schemas/CreditsafeGlobalDataAddressData'
        additionalData:
          $ref: >-
            #/components/schemas/CreditsafeGlobalDataReportsConsumerConsumerInformationAdditionalData
    CreditsafeGlobalDataReportsConsumerConsumerIncome:
      type: object
      properties:
        incomeYear:
          type: integer
          format: int32
        taxClass:
          type: string
        netWealth:
          type: number
          format: double
          nullable: true
        netIncome:
          type: number
          format: double
          nullable: true
        sumTax:
          type: number
          format: double
          nullable: true
        grossIncome:
          type: number
          format: double
          nullable: true
        municipalityNr:
          type: string
    CreditsafeGlobalDataReportsConsumerConsumerDirectorship:
      type: object
      properties:
        companyName:
          type: string
        companyStatus:
          type: string
        appointmentDate:
          type: string
          format: date-time
          nullable: true
        turnover:
          type: number
          format: double
          nullable: true
        creditRating:
          type: string
        companyNumber:
          type: string
        function:
          type: string
        companyRegistrationDate:
          type: string
          format: date-time
          nullable: true
        netWorth:
          type: number
          format: double
          nullable: true
        creditLimit:
          type: number
          format: double
          nullable: true
    CreditsafeGlobalDataReportsConsumerConsumerPaymentSummary:
      type: object
      properties:
        unsettledROPNumber:
          type: integer
          format: int32
          nullable: true
        partlySettledROPNumber:
          type: integer
          format: int32
          nullable: true
        voluntaryPledgeNumber:
          type: integer
          format: int32
          nullable: true
        unsettledROPAmount:
          type: number
          format: double
          nullable: true
        partlySettledROPAmount:
          type: number
          format: double
          nullable: true
        voluntaryPledgeAmount:
          type: number
          format: double
          nullable: true
    CreditsafeGlobalDataReportsConsumerConsumerRemarkOfPayment:
      type: object
      properties:
        type:
          type: string
        date:
          type: string
          format: date-time
          nullable: true
        source:
          type: string
        refNr:
          type: string
        amount:
          type: number
          format: double
          nullable: true
        creditor:
          type: string
        status:
          type: string
    CreditsafeGlobalDataReportsRangeDescribedValue_1_SystemString:
      type: object
      properties:
        maxValue:
          type: string
          description: The maximum value of the score that is provided for the Country.
        minValue:
          type: string
          description: The minimum value of the score that is provided for the Country.
        value:
          type: string
          description: >-
            Local credit score, as used by the supplier in that particular
            country
    CreditsafeGlobalDataReportsConsumerConsumerCreditRating:
      type: object
      properties:
        providerValue:
          $ref: >-
            #/components/schemas/CreditsafeGlobalDataReportsRangeDescribedValue_1_SystemString
        providerDescription:
          type: string
    CreditsafeGlobalDataCurrency:
      description: >-
        The Currency in which the financial value is displayed, as a
        three-character ISO code.
      enum:
        - AFA
        - ALL
        - DZD
        - ADF
        - ADP
        - AOA
        - ARA
        - ARS
        - AMD
        - AWG
        - AUD
        - AZM
        - BSD
        - BHD
        - BDT
        - BBD
        - BYR
        - BZD
        - BMD
        - BTN
        - BOB
        - BAM
        - BWP
        - BRC
        - BRL
        - GBP
        - BND
        - BGN
        - BIF
        - XOF
        - XAF
        - KHR
        - CAD
        - CVE
        - KYD
        - CLP
        - CNY
        - COP
        - KMF
        - CDF
        - CRC
        - HRK
        - CUP
        - CZK
        - DKK
        - DJF
        - DOP
        - NLG
        - EUR
        - ECS
        - EGP
        - SVC
        - EEK
        - ETB
        - FKP
        - FJD
        - FRF
        - GMD
        - GEL
        - GHC
        - GIP
        - XAU
        - GTQ
        - GNF
        - GWP
        - GYD
        - HTG
        - HNL
        - HKD
        - HUF
        - ISK
        - INR
        - IDR
        - IRR
        - IQD
        - ILS
        - JMD
        - JPY
        - JOD
        - KZT
        - KES
        - KRW
        - KWD
        - KGS
        - LAK
        - LVL
        - LBP
        - LSL
        - LRD
        - LYD
        - LTL
        - MOP
        - MKD
        - MGF
        - MWK
        - MYR
        - MVR
        - MTL
        - MRO
        - MUR
        - MXN
        - MDL
        - MNT
        - MAD
        - MZM
        - MMK
        - ANG
        - NAD
        - NPR
        - NZD
        - NIO
        - NGN
        - KPW
        - NOK
        - OMR
        - PKR
        - XPD
        - PAB
        - PGK
        - PYG
        - PEN
        - PHP
        - XPT
        - PLN
        - QAR
        - RON
        - RUB
        - RWF
        - WST
        - STD
        - SAR
        - RSD
        - SCR
        - SLL
        - XAG
        - SGD
        - SKK
        - SIT
        - SBD
        - SOS
        - ZAR
        - LKR
        - SHP
        - SDD
        - SDG
        - SDP
        - SRD
        - SRG
        - SZL
        - SEK
        - CHF
        - SYP
        - TWD
        - TJS
        - TZS
        - THB
        - TOP
        - TTD
        - TND
        - TRY
        - TMM
        - USD
        - UGX
        - UAG
        - UAK
        - AED
        - UYU
        - UZS
        - VUV
        - VEF
        - VND
        - YUN
        - ZMK
        - ZWD
        - AFN
        - ATS
        - AZN
        - BYN
        - BEF
        - BOV
        - GRD
        - FIM
        - DEM
        - GHS
        - IEP
        - ITL
        - LUF
        - PTE
        - ESP
        - XDR
        - TMT
        - UAH
        - ERN
        - MGA
        - MRU
        - MZN
        - SSP
        - STN
        - YER
        - XPF
        - XCD
        - ZMW
        - ZWL
      type: string
    CreditsafeGlobalDataReportsFinancialValue_1_SystemDecimal:
      type: object
      properties:
        currency:
          $ref: '#/components/schemas/CreditsafeGlobalDataCurrency'
        value:
          type: number
          format: double
          description: >-
            The maximum amount of share capital the company is authorised by its
            constitutional documents to issue to shareholders.
    CreditsafeGlobalDataReportsCommonRatingValue:
      description: Standardised credit score – will be A, B, C, D or E.
      enum:
        - A
        - B
        - C
        - D
        - E
      type: string
    CreditsafeGlobalDataReportsFinancialValue_1_SystemString:
      type: object
      properties:
        currency:
          $ref: '#/components/schemas/CreditsafeGlobalDataCurrency'
        value:
          type: string
          description: Amount of credit advisable at any one time.
    CreditsafeGlobalDataReportsCreditRating:
      type: object
      properties:
        commonValue:
          $ref: '#/components/schemas/CreditsafeGlobalDataReportsCommonRatingValue'
        commonDescription:
          type: string
          description: A text description of the common credit score.
        creditLimit:
          $ref: >-
            #/components/schemas/CreditsafeGlobalDataReportsFinancialValue_1_SystemString
        providerValue:
          $ref: >-
            #/components/schemas/CreditsafeGlobalDataReportsRangeDescribedValue_1_SystemString
        providerDescription:
          type: string
          description: Local credit score description.
        pod:
          type: number
          format: double
          nullable: true
          description: >-
            Probability of Default (POD) is the anticipated likelihood of
            company default within the next 12 months in a percentage format.
        assessment:
          type: string
          description: An additional score assessment commentary.
    CreditsafeGlobalDataReportsConsumerConsumerCreditScore:
      type: object
      properties:
        currentCreditRating:
          $ref: >-
            #/components/schemas/CreditsafeGlobalDataReportsConsumerConsumerCreditRating
        currentContractLimit:
          $ref: >-
            #/components/schemas/CreditsafeGlobalDataReportsFinancialValue_1_SystemDecimal
        previousCreditRating:
          $ref: '#/components/schemas/CreditsafeGlobalDataReportsCreditRating'
        latestRatingChangeDate:
          type: string
          format: date-time
          nullable: true
    CreditsafeGlobalDataReportsConsumerConsumerAdditionalInformation:
      type: object
    CreditsafeGlobalDataReportsConsumerConsumerReport:
      type: object
      properties:
        consumerInformation:
          $ref: >-
            #/components/schemas/CreditsafeGlobalDataReportsConsumerConsumerInformation
        incomes:
          type: array
          items:
            $ref: >-
              #/components/schemas/CreditsafeGlobalDataReportsConsumerConsumerIncome
        registeredProperty:
          type: integer
          format: int32
          nullable: true
        registeredHousingShare:
          type: integer
          format: int32
          nullable: true
        directorships:
          type: array
          items:
            $ref: >-
              #/components/schemas/CreditsafeGlobalDataReportsConsumerConsumerDirectorship
        paymentRemarks:
          type: array
          items:
            $ref: >-
              #/components/schemas/CreditsafeGlobalDataReportsConsumerConsumerPaymentSummary
        paymentRemarksDetails:
          type: array
          items:
            $ref: >-
              #/components/schemas/CreditsafeGlobalDataReportsConsumerConsumerRemarkOfPayment
        voluntaryPledges:
          type: array
          items:
            $ref: >-
              #/components/schemas/CreditsafeGlobalDataReportsConsumerConsumerRemarkOfPayment
        consumerRating:
          $ref: >-
            #/components/schemas/CreditsafeGlobalDataReportsConsumerConsumerCreditScore
        additionalInformation:
          $ref: >-
            #/components/schemas/CreditsafeGlobalDataReportsConsumerConsumerAdditionalInformation
    ConnectErrorResponsesBadRequest:
      type: object
      description: Bad Request
      properties:
        correlationId:
          type: string
          description: A unique ID assigned to this request.
        message:
          type: string
        details:
          type: string
          description: Provides further information on why the request was rejected
    CreditsafeGlobalDataReportsConsumerCriteriaSet:
      properties:
        countries:
          type: array
          items:
            $ref: '#/components/schemas/CreditsafeGlobalDataCountryCode'
        criteriaSets:
          type: array
          items:
            type: object
security:
  - bearerToken: []
