openapi: 3.1.0
info:
  title: Search Engine
  x-metadata:
    status: published
    tags:
      - Sweden
  description: >-
    The Integrated Search Engine REST API enables you to search for a company's
    organization number  or a consumer's personal identification number using
    details such as name, address, postal code,  city, or any combination of
    these.
  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 Search
    description: Search operations for company data
  - name: Consumer Search
    description: Search operations for consumer data
  - name: Health Check
    description: Service health check endpoint
paths:
  /search/company:
    get:
      tags:
        - Company Search
      operationId: searchCompany
      summary: Search for company data
      description: >-
        Search for companies using organization number, name, address, or other
        details. Returns company information including organization number,
        name, address, status, and other details.


        **Important:** At least one of the following parameters is required to
        perform a search:  `namesearchnumber`, `address`, `cityorpostcode`, or
        `telephone`.
      parameters:
        - name: namesearchnumber
          in: query
          required: false
          description: >-
            Complete or part of the company's name or the complete organization
            number (without hyphen). Name search is not case sensitive.  


            **Note:** At least one search parameter (namesearchnumber, address,
            cityorpostcode, or telephone) is required.
          schema:
            type: string
            maxLength: 255
        - name: address
          in: query
          required: false
          description: >-
            Street address (with or without address number).  


            **Note:** At least one search parameter (namesearchnumber, address,
            cityorpostcode, or telephone) is required.
          schema:
            type: string
            maxLength: 255
        - name: cityorpostcode
          in: query
          required: false
          description: >-
            City and/or the post code (5 digits without space, e.g. "12345").  


            **Note:** At least one search parameter (namesearchnumber, address,
            cityorpostcode, or telephone) is required.
          schema:
            type: string
            maxLength: 60
        - name: telephone
          in: query
          required: false
          description: >-
            Telephone number with or without hyphen.  

            Note: This search value will actually also give a response if the
            number matches a fax. Only available for company search. Maximum 20
            characters (will be truncated if longer).


            **Note:** At least one search parameter (namesearchnumber, address,
            cityorpostcode, or telephone) is required.
          schema:
            type: string
            maxLength: 20
        - name: companytype
          in: query
          required: false
          description: >-
            Company type filter. Accepted values are AB, EF, HBKB (combined HB
            and KB), or Other. Can be used individually or combined.
          schema:
            type: string
            enum:
              - AB
              - EF
              - HBKB
              - Other
        - name: includeinactive
          in: query
          required: false
          description: >-
            Whether to include inactive companies in the search results. Default
            is false (inactive companies are excluded).
          schema:
            type: boolean
            default: false
        - name: startposition
          in: query
          required: false
          description: >-
            Start position of the search result, must be between 1-100. Used if
            more than 50 search results in response. Default value is 1.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 1
        - name: pagesize
          in: query
          required: false
          description: >-
            Number of search results returned in the response. Must be between
            1-50. Default is 25.
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 25
        - 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
        - name: language
          in: query
          required: false
          description: Sets the language of the response
          schema:
            type: string
            enum:
              - sv
              - en
            default: en
      responses:
        '200':
          description: Successful response with company search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanySearchResponse'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Authentication or authorization error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found - No results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerToken: []
  /search/consumer:
    get:
      tags:
        - Consumer Search
      operationId: searchConsumer
      summary: Search for consumer data
      description: >-
        Search for individuals using personal identification number, name,
        address, or other details. Returns consumer information including
        personal identification number, name, address, status, and other
        details.


        **Important:** At least one of the following parameters is required to
        perform a search:  `namesearchnumber`, `address`, or `cityorpostcode`.
      parameters:
        - name: namesearchnumber
          in: query
          required: false
          description: >-
            Complete or part of person's name or complete personal identity
            number (without hyphen). Name search is not case sensitive.  


            **Note:** At least one search parameter (namesearchnumber, address,
            or cityorpostcode) is required.
          schema:
            type: string
            maxLength: 255
        - name: address
          in: query
          required: false
          description: >-
            Street address (with or without address number).  


            **Note:** At least one search parameter (namesearchnumber, address,
            or cityorpostcode) is required.
          schema:
            type: string
            maxLength: 255
        - name: cityorpostcode
          in: query
          required: false
          description: >-
            City and/or the post code (5 digits without space, e.g. "12345").  


            **Note:** At least one search parameter (namesearchnumber, address,
            or cityorpostcode) is required.
          schema:
            type: string
            maxLength: 60
        - name: includeinactive
          in: query
          required: false
          description: >-
            Whether to include inactive consumers in the search results. Default
            is false (inactive consumers are excluded).
          schema:
            type: boolean
            default: false
        - name: startposition
          in: query
          required: false
          description: >-
            Start position of the search result, must be between 1-100. Used if
            more than 50 search results in response. Default value is 1.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 1
        - name: pagesize
          in: query
          required: false
          description: >-
            Number of search results returned in the response. Must be between
            1-50. Default is 25.
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 25
        - 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
        - name: language
          in: query
          required: false
          description: Sets the language of the response
          schema:
            type: string
            enum:
              - sv
              - en
            default: en
      responses:
        '200':
          description: Successful response with consumer search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsumerSearchResponse'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Authentication or authorization error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found - No results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerToken: []
  /search/health:
    get:
      tags:
        - Health Check
      operationId: healthCheck
      summary: Health Check Endpoint
      description: >-
        Returns the health status of the Search Engine service. This endpoint
        should be used exclusively for service availability checks. It is free
        of charge, safe for production environments, and designed for monitoring
        tools and automated checks.
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthCheckResponse'
              example:
                status: healthy
                service: Company Search (1225)
                timestamp: '2025-09-15T13:27:14.3794136Z'
                version: production
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:
    Address:
      type: object
      description: Address details.
      properties:
        careOf:
          type: string
          description: C/O address.
        street:
          type: string
          description: Street address.
        zipCode:
          type: integer
          description: Zip code.
        town:
          type: string
          description: Town or city.
        addressType:
          type: integer
          description: Address type code.
        addressTypeText:
          type: string
          description: Address type description.
    CompanySearchResult:
      type: object
      description: Company search result item.
      properties:
        organizationNumber:
          type: string
          description: Company organization number
        companyName:
          type: string
          description: Company name.
        previousCompanyName:
          type: string
          description: Old company name.
        address:
          $ref: '#/components/schemas/Address'
        oldAddress:
          $ref: '#/components/schemas/Address'
        phone:
          type: string
          description: Phone number.
        statusType:
          type: string
          description: Status type.
        statusText:
          type: string
          description: Status type text.
        isPartOfGroup:
          type: boolean
          description: Whether the company is part of a group.
        lastAccountPeriod:
          type: string
          description: Latest annual account period.
        companyType:
          type: string
          description: Company type.
        companyTypeText:
          type: string
          description: Company type text.
        companyLegalGroup:
          type: string
          description: Company legal group.
    CompanySearchResponse:
      type: object
      description: Company search response.
      properties:
        metaData:
          type: object
          description: Metadata about the request
          properties:
            apiLogId:
              type: integer
              description: Unique identifier for the Creditsafe API log
            timeStamp:
              type: string
              format: date-time
              description: The exact time when the request was processed
            resource:
              type: string
              description: Which service delivered the report
            method:
              type: string
              description: The HTTP method used for the request
            requestUrl:
              type: string
              description: The complete URL of the request
        report:
          type: object
          description: Report object containing search results
          properties:
            results:
              type: array
              description: Array of company search results
              items:
                $ref: '#/components/schemas/CompanySearchResult'
            totalCount:
              type: integer
              description: Total number of results found
    Error:
      type: object
      description: >-
        Error response for failed requests. 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: 547631
            timeStamp:
              type: string
              format: date-time
              description: The exact time when the request was processed
              example: '2026-07-21T09:12:41'
            resource:
              type: string
              description: Which service delivered the response
              example: Company Search (1225)
            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/search/company?namesearchnumber=test
        error:
          type: object
          description: Error details
          required:
            - code
            - text
          properties:
            code:
              type: string
              description: Error code
              example: '15'
            text:
              type: string
              description: Error message text
              example: No match record
            detail:
              type: string
              description: >-
                Additional error details. This property is optional and may be
                omitted entirely when no additional context is available.
    ConsumerSearchResult:
      type: object
      description: Consumer search result item.
      properties:
        personalIdentificationNumber:
          type: string
          description: Person's identity number (12 digits)
        name:
          type: string
          description: Name of the consumer.
        givenName:
          type: string
          description: Given name.
        previousName:
          type: string
          description: Previous name.
        statusTypeText:
          type: string
          description: Status type text.
        statusType:
          type: string
          description: Status type.
        isActive:
          type: boolean
          description: Whether the consumer is active.
        address:
          description: Registered address
          $ref: '#/components/schemas/Address'
        oldAddress:
          description: Previous address if available
          $ref: '#/components/schemas/Address'
        specialAddress:
          description: Special postal address if registered
          $ref: '#/components/schemas/Address'
        oldSpecialAddress:
          description: Previous special address if available
          $ref: '#/components/schemas/Address'
    ConsumerSearchResponse:
      type: object
      description: Consumer search response.
      properties:
        metaData:
          type: object
          description: Metadata about the request
          properties:
            apiLogId:
              type: integer
              description: Unique identifier for the Creditsafe API log
            timeStamp:
              type: string
              format: date-time
              description: The exact time when the request was processed
            resource:
              type: string
              description: Which service delivered the report
            method:
              type: string
              description: The HTTP method used for the request
            requestUrl:
              type: string
              description: The complete URL of the request
        report:
          type: object
          description: Report object containing search results
          properties:
            results:
              type: array
              description: Array of consumer search results
              items:
                $ref: '#/components/schemas/ConsumerSearchResult'
            totalCount:
              type: integer
              description: Total number of results found
    HealthCheckResponse:
      type: object
      description: Health check response model for monitoring service availability.
      properties:
        status:
          type: string
          description: Overall health status of the service.
        service:
          type: string
          description: Service name.
        timestamp:
          type: string
          format: date-time
          description: Current timestamp.
        version:
          type: string
          description: Service version/environment.
security:
  - bearerToken: []
