{
  "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.\n\n**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.  \n\n**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).  \n\n**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\").  \n\n**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.  \nNote: 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).\n\n**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.\n\n**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.  \n\n**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).  \n\n**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\").  \n\n**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": []
    }
  ]
}