openapi: 3.1.0
info:
  title: Date Check
  x-metadata:
    status: published
    tags:
      - Sweden
  description: >-
    The Creditsafe DateCheck REST API allows you to monitor changes and avoid
    fetching  more data than necessary. With DateCheck, you can verify if any of
    the included  categories has changed on a consumer or company since a
    specific date. The API enables  you to compare the date of your most recent
    credit decision with the latest date of  change, helping you avoid
    unnecessary credit checks and letters of disclosure.
  version: 1.0.0
  contact:
    name: Creditsafe Integration Team
    email: integration@creditsafe.se
servers:
  - url: https://se-webservice.apps.creditsafe.com
    description: Production server
  - url: https://se-webservice-sandbox.apps.creditsafe.com
    description: Sandbox server
tags:
  - name: Company
    description: Company date check operations
  - name: Consumer
    description: Consumer date check operations
  - name: Health Check
    description: Service health check endpoint
paths:
  /datecheck/company:
    get:
      tags:
        - Company
      operationId: companyDateCheck
      summary: Check Company Data Changes Since Reference Date
      description: >-
        Verify if any of the included categories has changed for a company since
        a specific  reference date. Returns a list of change codes with the
        dates they occurred. The  reference date cannot be older than 60 months
        for limited companies (aktiebolag),  trading companies (handelsbolag),
        or partnerships (kommanditbolag).
      parameters:
        - name: searchnumber
          in: query
          required: true
          description: Organization number (10-12 digits). Only digits are allowed.
          schema:
            type: string
            maxLength: 12
            pattern: ^\d{10,12}$
            example: '5565144408'
        - name: referencedate
          in: query
          required: true
          description: >-
            The date from which the changes will be calculated. Cannot be older
            than 60 months. Accepted formats: YYYY-MM-DD, YYYYMMDD, YYMMDD
          schema:
            type: string
            maxLength: 10
            pattern: ^(\d{6}|\d{8}|\d{4}-\d{2}-\d{2})$
            example: '2020-08-29'
        - name: transactionid
          in: query
          required: false
          description: >-
            Optional. Customer's internal information (customer/invoice number).
            Recommended  to use this field as it can be helpful in tracking your
            call in Creditsafe logs.
          schema:
            type: string
            maxLength: 14
            example: X123
        - name: language
          in: query
          required: false
          description: >-
            Sets the language of the response. Available languages: sv (Swedish)
            or en (English)
          schema:
            type: string
            maxLength: 3
            enum:
              - en
              - sv
            example: sv
            default: en
        - name: legacyformat
          in: query
          required: false
          description: >-
            Optional. Pass true to receive the old SOAP parameter format from
            previous versions.  Leave out or send false for the new REST API
            format.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/DateCheckAuroraResponse'
                  - $ref: '#/components/schemas/DateCheckAurora_LEGACY_Response'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /datecheck/consumer:
    get:
      tags:
        - Consumer
      operationId: consumerDateCheck
      summary: Check consumer data changes since reference date
      description: >-
        Verify if any of the included categories has changed for a consumer
        since a specific  reference date. Returns a list of change codes with
        the dates they occurred. The  reference date cannot be older than 36
        months for consumers or sole traders  (enskilda firmor).
      parameters:
        - name: searchnumber
          in: query
          required: true
          description: Person number (12 digits). Only digits are allowed.
          schema:
            type: string
            maxLength: 12
            pattern: ^\d{12}$
            example: '198001010001'
        - name: referencedate
          in: query
          required: true
          description: >-
            The date from which the changes will be calculated. Cannot be older
            than 36 months. Accepted formats: YYYY-MM-DD, YYYYMMDD, YYMMDD
          schema:
            type: string
            maxLength: 10
            pattern: ^(\d{6}|\d{8}|\d{4}-\d{2}-\d{2})$
            example: '2024-01-01'
        - name: transactionid
          in: query
          required: false
          description: >-
            Optional. Customer's internal information (customer/invoice number).
            Recommended  to use this field as it can be helpful in tracking your
            call in Creditsafe logs.
          schema:
            type: string
            maxLength: 14
            example: X123
        - name: language
          in: query
          required: false
          description: >-
            Sets the language of the response. Available languages: sv (Swedish)
            or en (English)
          schema:
            type: string
            maxLength: 3
            enum:
              - en
              - sv
            example: sv
            default: en
        - name: legacyformat
          in: query
          required: false
          description: >-
            Optional. Pass true to receive the old SOAP parameter format from
            previous versions.  Leave out or send false for the new REST API
            format.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/DateCheckOracleResponse'
                  - $ref: '#/components/schemas/DateCheckOracle_LEGACY_Response'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /datecheck/health:
    get:
      tags:
        - Health Check
      operationId: healthCheck
      summary: Service Health Check
      description: >-
        Lightweight endpoint to verify that the DateCheck service is
        operational.  This endpoint is designed exclusively for service
        availability checks and  should be used instead of making fake service
        calls with invalid data.


        **Important:** Never use regular service calls for availability checks
        by  using invalid or random search criteria, repeated queries against
        real companies  or individuals, or automated loops that simulate usage.
        Always use this health  endpoint for system availability verification.
      security: []
      responses:
        '200':
          description: Service is healthy and operational
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Health status of the service
                    example: healthy
                  service:
                    type: string
                    description: Name of the service
                    example: DateCheck Company (1219)
                  timestamp:
                    type: string
                    format: date-time
                    description: ISO 8601 timestamp of the health check
                    example: '2025-09-15T13:27:14.3794136Z'
                  version:
                    type: string
                    description: Service version/environment
                    example: production
              example:
                status: healthy
                service: DateCheck Company (1219)
                timestamp: '2025-09-15T13:27:14.3794136Z'
                version: production
components:
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        JWT token obtained from CONNECT Authenticate API. Include as 
        'Authorization: Bearer {token}' in the request header.
  schemas:
    DateCheckAuroraResponse:
      type: object
      description: DateCheck response for company searches
      properties:
        metaData:
          type: object
          description: >-
            Metadata section containing request information for tracing and
            troubleshooting
          properties:
            apiLogId:
              type: integer
              description: >-
                Unique identifier for the Creditsafe API log. Refer to this ID
                when contacting support
              example: 233255
            timeStamp:
              type: string
              format: date-time
              description: The exact time when the request was processed by Creditsafe
              example: '2025-10-06T06:12:03'
            resource:
              type: string
              description: Indicates which service delivered the report
              example: DateCheck Company (1219)
            method:
              type: string
              description: Specifies the HTTP method used for the request
              example: GET
            requestUrl:
              type: string
              description: The complete URL of the request sent to Creditsafe
              example: >-
                https://se-webservice.apps.creditsafe.com/datecheck/company?language=sv&referencedate=2023-01-01&searchnumber=5565144408
        report:
          type: array
          description: List of change codes with dates when changes occurred
          items:
            type: object
            properties:
              code:
                type: string
                description: Change code as described in the change categories
                example: RAT
              description:
                type: string
                description: >-
                  Description of the change code, available in English or
                  Swedish
                example: Rating
              changeDate:
                type: string
                format: date-time
                description: Date when the change occurred. Format YYYY-MM-DDTHH:MM:SS
                example: '2022-12-02T00:00:00'
            required:
              - code
              - description
              - changeDate
      required:
        - report
    DateCheckAurora_LEGACY_Response:
      type: object
      description: DateCheck response with legacy field names (when legacyformat=true)
      properties:
        metaData:
          type: object
          description: >-
            Metadata section containing request information for tracing and
            troubleshooting
          properties:
            apiLogId:
              type: integer
              description: >-
                Unique identifier for the Creditsafe API log. Refer to this ID
                when contacting support
              example: 542902
            timeStamp:
              type: string
              format: date-time
              description: The exact time when the request was processed by Creditsafe
              example: '2026-07-15T14:27:17'
            resource:
              type: string
              description: Indicates which service delivered the report
              example: DateCheck Company (1219)
            method:
              type: string
              description: Specifies the HTTP method used for the request
              example: GET
            requestUrl:
              type: string
              description: The complete URL of the request sent to Creditsafe
              example: >-
                https://se-webservice.apps-dev.creditsafe.com/datecheck/company?language=en&legacyformat=true&referencedate=2024-01-01&searchnumber=5565144408
          required:
            - apiLogId
            - timeStamp
            - resource
            - method
            - requestUrl
        report:
          type: array
          description: >-
            List of change codes with dates when changes occurred (legacy field
            names)
          items:
            type: object
            properties:
              ChangeCode:
                type: string
                description: >-
                  Change code as described in the change categories (legacy
                  format)
                example: DTA
              ChangeDescription:
                type: string
                description: >-
                  Description of the change code, available in English or
                  Swedish (legacy format)
                example: Distraint/Repossesion
              ChangeDate:
                type: string
                format: date-time
                description: >-
                  Date when the change occurred (legacy format). Format
                  YYYY-MM-DDTHH:MM:SS
                example: '2025-02-27T00:00:00'
            required:
              - ChangeCode
              - ChangeDescription
              - ChangeDate
      required:
        - report
        - metaData
    ErrorResponse:
      type: object
      description: >-
        Error response structure. All error responses include metaData and error
        only. Null fields are omitted from the JSON response.
      required:
        - metaData
        - error
      properties:
        metaData:
          type: object
          description: Metadata about the request
          required:
            - apiLogId
            - timeStamp
            - resource
            - method
            - requestUrl
          properties:
            apiLogId:
              type: integer
              description: Unique identifier for the Creditsafe API log
              example: 547637
            timeStamp:
              type: string
              format: date-time
              description: The exact time when the request was processed
              example: '2026-07-21T09:14:33'
            resource:
              type: string
              description: Which service delivered the response
              example: DateCheck Company (1219)
            method:
              type: string
              description: The HTTP method used for the request
              example: GET
            requestUrl:
              type: string
              description: The complete URL of the request
              example: >-
                https://se-webservice.apps.creditsafe.com/datecheck/company?searchnumber=5565144408
            lodCreated:
              type: boolean
              description: >-
                Whether a letter of disclosure was created (DateCheck only, may
                be omitted)
              example: false
        error:
          type: object
          description: Error details
          required:
            - code
            - text
          properties:
            code:
              type: string
              description: Error code
              example: '23'
            text:
              type: string
              description: Error description
              example: Reference date too old
            detail:
              type: string
              description: >-
                Additional detail about the error. This property is optional and
                may be omitted entirely when no additional context is available.
              example: Reference date may not be older than 2021-07-21
    DateCheckOracleResponse:
      type: object
      description: DateCheck response for consumer searches
      properties:
        metaData:
          type: object
          description: >-
            Metadata section containing request information for tracing and
            troubleshooting
          properties:
            apiLogId:
              type: integer
              description: >-
                Unique identifier for the Creditsafe API log. Refer to this ID
                when contacting support
              example: 233256
            timeStamp:
              type: string
              format: date-time
              description: The exact time when the request was processed by Creditsafe
              example: '2025-10-06T06:12:05'
            resource:
              type: string
              description: Indicates which service delivered the report
              example: DateCheck Consumer (1220)
            method:
              type: string
              description: Specifies the HTTP method used for the request
              example: GET
            requestUrl:
              type: string
              description: The complete URL of the request sent to Creditsafe
              example: >-
                https://se-webservice.apps.creditsafe.com/datecheck/consumer?language=sv&referencedate=2023-01-01&searchnumber=198001010001
        report:
          type: array
          description: List of change codes with dates when changes occurred
          items:
            type: object
            properties:
              code:
                type: string
                description: Change code as described in the change categories
                example: SCO
              description:
                type: string
                description: >-
                  Description of the change code, available in English or
                  Swedish
                example: Scoring
              changeDate:
                type: string
                format: date-time
                description: Date when the change occurred. Format YYYY-MM-DDTHH:MM:SS
                example: '2024-06-13T00:00:00'
            required:
              - code
              - description
              - changeDate
      required:
        - report
    DateCheckOracle_LEGACY_Response:
      type: object
      description: >-
        DateCheck response for consumer with legacy field names (when
        legacyformat=true)
      properties:
        metaData:
          type: object
          description: >-
            Metadata section containing request information for tracing and
            troubleshooting
          properties:
            apiLogId:
              type: integer
              description: >-
                Unique identifier for the Creditsafe API log. Refer to this ID
                when contacting support
              example: 542902
            timeStamp:
              type: string
              format: date-time
              description: The exact time when the request was processed by Creditsafe
              example: '2026-07-15T14:27:17'
            resource:
              type: string
              description: Indicates which service delivered the report
              example: DateCheck Consumer (1220)
            method:
              type: string
              description: Specifies the HTTP method used for the request
              example: GET
            requestUrl:
              type: string
              description: The complete URL of the request sent to Creditsafe
              example: >-
                https://se-webservice.apps-dev.creditsafe.com/datecheck/consumer?language=en&legacyformat=true&referencedate=2024-01-01&searchnumber=198001010001
          required:
            - apiLogId
            - timeStamp
            - resource
            - method
            - requestUrl
        report:
          type: array
          description: >-
            List of change codes with dates when changes occurred (legacy field
            names)
          items:
            type: object
            properties:
              ChangeCode:
                type: string
                description: >-
                  Change code as described in the change categories (legacy
                  format)
                example: DEP
              ChangeDescription:
                type: string
                description: >-
                  Description of the change code, available in English or
                  Swedish (legacy format)
                example: Payment remark private
              ChangeDate:
                type: string
                format: date-time
                description: >-
                  Date when the change occurred (legacy format). Format
                  YYYY-MM-DDTHH:MM:SS
                example: '2026-03-20T00:00:00'
            required:
              - ChangeCode
              - ChangeDescription
              - ChangeDate
      required:
        - report
        - metaData
  responses:
    BadRequest:
      description: Bad request - invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalid_language:
              summary: Invalid language parameter.
              value:
                metaData:
                  apiLogId: 547700
                  timeStamp: '2026-07-21T10:00:00'
                  resource: DateCheck Company (1219)
                  method: GET
                  requestUrl: >-
                    https://se-webservice.apps.creditsafe.com/datecheck/company?language=xx
                error:
                  code: R1
                  text: Invalid language parameter.
            missing_reference_date:
              summary: Missing reference date.
              value:
                metaData:
                  apiLogId: 547701
                  timeStamp: '2026-07-21T10:01:00'
                  resource: DateCheck Company (1219)
                  method: GET
                  requestUrl: >-
                    https://se-webservice.apps.creditsafe.com/datecheck/company?searchnumber=5565144408
                error:
                  code: '21'
                  text: Reference date is required.
            invalid_date_format:
              summary: Invalid date format.
              value:
                metaData:
                  apiLogId: 547702
                  timeStamp: '2026-07-21T10:02:00'
                  resource: DateCheck Company (1219)
                  method: GET
                  requestUrl: >-
                    https://se-webservice.apps.creditsafe.com/datecheck/company?searchnumber=5565144408&referencedate=invalid
                error:
                  code: '22'
                  text: >-
                    Reference date must be in format yyMMdd, yyyyMMdd or
                    yyyy-mm-dd.
                  detail: >-
                    Referensdatumformatet ska vara yyMMdd, yyyyMMdd or
                    yyyy-mm-dd
            date_too_old:
              summary: Reference date too old.
              value:
                metaData:
                  apiLogId: 547703
                  timeStamp: '2026-07-21T10:03:00'
                  resource: DateCheck Company (1219)
                  method: GET
                  requestUrl: >-
                    https://se-webservice.apps.creditsafe.com/datecheck/company?searchnumber=5565144408&referencedate=2020-01-01
                error:
                  code: '23'
                  text: Reference date cannot be older than specified limit.
                  detail: Referensdatum får inte vara äldre än yyyy-mm-dd
    Forbidden:
      description: Forbidden - access denied or insufficient permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            no_access_to_company_type:
              summary: No access to company type.
              value:
                metaData:
                  apiLogId: 547710
                  timeStamp: '2026-07-21T10:10:00'
                  resource: DateCheck Company (1219)
                  method: GET
                  requestUrl: >-
                    https://se-webservice.apps.creditsafe.com/datecheck/company?searchnumber=5565144408&referencedate=2025-01-01
                error:
                  code: '17'
                  text: No access to this company type.
                  detail: Ej tillgång till denna företagstyp – AB
            service_access_denied_account:
              summary: Service access denied for account.
              value:
                metaData:
                  apiLogId: 547711
                  timeStamp: '2026-07-21T10:11:00'
                  resource: DateCheck Company (1219)
                  method: GET
                  requestUrl: >-
                    https://se-webservice.apps.creditsafe.com/datecheck/company?searchnumber=5565144408&referencedate=2025-01-01
                error:
                  code: '7'
                  text: Access denied to this service.
                  detail: Ditt kundkonto har inte tjänsten DateCheck Company (1219)
            service_access_denied_user:
              summary: Service access denied for user.
              value:
                metaData:
                  apiLogId: 547712
                  timeStamp: '2026-07-21T10:12:00'
                  resource: DateCheck Company (1219)
                  method: GET
                  requestUrl: >-
                    https://se-webservice.apps.creditsafe.com/datecheck/company?searchnumber=5565144408&referencedate=2025-01-01
                error:
                  code: '7'
                  text: Access denied to this service.
                  detail: Användaren har inte tjänsten DateCheck Company (1219)
            quota_exhausted:
              summary: Report quota exhausted.
              value:
                metaData:
                  apiLogId: 547713
                  timeStamp: '2026-07-21T10:13:00'
                  resource: DateCheck Company (1219)
                  method: GET
                  requestUrl: >-
                    https://se-webservice.apps.creditsafe.com/datecheck/company?searchnumber=5565144408&referencedate=2025-01-01
                error:
                  code: '8'
                  text: Reports/credits exhausted.
                  detail: >-
                    Inga kvarvarande rapporter för kontot eller användaren till
                    tjänsten DateCheck Company (1219)
    NotFound:
      description: Not found - no match for search number.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            no_match:
              summary: No match record.
              value:
                metaData:
                  apiLogId: 547720
                  timeStamp: '2026-07-21T10:20:00'
                  resource: DateCheck Company (1219)
                  method: GET
                  requestUrl: >-
                    https://se-webservice.apps.creditsafe.com/datecheck/company?searchnumber=9999999999&referencedate=2025-01-01
                error:
                  code: '15'
                  text: No match record.
            invalid_search_number:
              summary: Invalid or empty search number.
              value:
                metaData:
                  apiLogId: 547721
                  timeStamp: '2026-07-21T10:21:00'
                  resource: DateCheck Company (1219)
                  method: GET
                  requestUrl: >-
                    https://se-webservice.apps.creditsafe.com/datecheck/company?referencedate=2025-01-01
                error:
                  code: '15'
                  text: No match record.
                  detail: Söknumret får inte saknas eller vara tomt
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            server_error:
              summary: Internal server error.
              value:
                metaData:
                  apiLogId: 547730
                  timeStamp: '2026-07-21T10:30:00'
                  resource: DateCheck Company (1219)
                  method: GET
                  requestUrl: >-
                    https://se-webservice.apps.creditsafe.com/datecheck/company?searchnumber=5565144408&referencedate=2025-01-01
                error:
                  code: '14'
                  text: Internal server error.
security:
  - bearerToken: []
