openapi: 3.1.0
info:
  title: Get Data Unit
  x-metadata:
    status: published
    tags:
      - Sweden
  description: >
    The GetDataUnit REST API enables you to retrieve a list of all units
    (offices, branches, etc.) 

    associated with an organization. This service provides detailed information
    about each unit including 

    office type, status, employee range, industry classification, addresses, and
    contact information.
  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: Data Retrieval
    description: Operations for retrieving company unit data
  - name: Health Check
    description: Service health check endpoint
paths:
  /getdataunit:
    get:
      tags:
        - Data Retrieval
      operationId: getDataUnit
      summary: Retrieve company unit data
      description: >-
        Retrieves company unit data based on search parameters. Returns 404 if
        not found or 400 for invalid input.
      parameters:
        - name: searchnumber
          in: query
          required: false
          description: >-
            Unique identifier used to search for a company or business entity.
            Organization number (typically 10 digits). The value is normalised
            by  the service before processing.
          schema:
            type: string
            maxLength: 10
        - name: name
          in: query
          required: false
          description: Company or business name used as search criteria.
          schema:
            type: string
        - name: address
          in: query
          required: false
          description: Address value used as search criteria.
          schema:
            type: string
        - name: postnr
          in: query
          required: false
          description: Postal code used as search criteria.
          schema:
            type: string
        - name: includeinactive
          in: query
          required: false
          description: When set to true, inactive entities are included in the results.
          schema:
            type: boolean
            default: false
        - name: legacyformat
          in: query
          required: false
          description: >-
            Controls whether the response is returned in a legacy format. If you
            leave this parameter out or send a false value you will get  the new
            format used in Creditsafe REST APIs. Pass true into this  parameter
            if you want the API to respond with the old SOAP parameter  format
            from previous versions of this service.
          schema:
            type: boolean
            default: false
        - name: language
          in: query
          required: false
          description: >-
            Language used for response content and messages. Supported values
            are English (en) and Swedish (sv).
          schema:
            type: string
            enum:
              - en
              - sv
            default: en
        - name: transactionid
          in: query
          required: false
          description: >-
            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
      responses:
        '200':
          description: Successful response with list of company units
          content:
            application/json:
              schema:
                type: object
                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
                      timeStamp:
                        type: string
                        format: date-time
                        description: >-
                          The exact time when the request was processed by
                          Creditsafe
                      resource:
                        type: string
                        description: Indicates which service delivered the report
                      method:
                        type: string
                        description: Specifies the HTTP method used for the request
                      requestUrl:
                        type: string
                        description: The complete URL of the request sent to Creditsafe
                    required:
                      - apiLogId
                      - timeStamp
                      - resource
                      - method
                      - requestUrl
                  report:
                    type: array
                    description: Array of company units for the organization
                    items:
                      $ref: '#/components/schemas/GetDataUnitRestResponse'
                required:
                  - metaData
                  - report
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidLanguage:
                  summary: Invalid language parameter
                  value:
                    metaData:
                      apiLogId: 547740
                      timeStamp: '2026-07-21T10:40:00'
                      resource: GetDataUnit (1218)
                      method: GET
                      requestUrl: >-
                        https://se-webservice.apps.creditsafe.com/getdataunit?searchnumber=5565144408&language=xx
                    error:
                      code: R1
                      text: >-
                        Språket måste vara antingen en (default) eller sv
                        (svenska)
        '403':
          description: Forbidden - Authentication or authorization error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                tokenExpired:
                  summary: Token has expired
                  value:
                    metaData:
                      apiLogId: 547740
                      timeStamp: '2026-07-21T10:40:00'
                      resource: GetDataUnit (1218)
                      method: GET
                      requestUrl: >-
                        https://se-webservice.apps.creditsafe.com/getdataunit?searchnumber=5565144408
                    error:
                      code: R4
                      text: Token har gått ut
                noAccess:
                  summary: No access to service
                  value:
                    metaData:
                      apiLogId: 547741
                      timeStamp: '2026-07-21T10:41:00'
                      resource: GetDataUnit (1218)
                      method: GET
                      requestUrl: >-
                        https://se-webservice.apps.creditsafe.com/getdataunit?searchnumber=5565144408
                    error:
                      code: '7'
                      text: Ej tillgång till tjänsten
                      detail: Ditt kundkonto har inte tjänsten GetDataUnit (1218)
                quotaExhausted:
                  summary: Report quota exhausted
                  value:
                    metaData:
                      apiLogId: 547742
                      timeStamp: '2026-07-21T10:42:00'
                      resource: GetDataUnit (1218)
                      method: GET
                      requestUrl: >-
                        https://se-webservice.apps.creditsafe.com/getdataunit?searchnumber=5565144408
                    error:
                      code: '8'
                      text: Rapporter/poäng slut
                      detail: >-
                        Inga kvarvarande rapporter för kontot eller användaren
                        till tjänsten GetDataUnit (1218)
        '404':
          description: Not found - Organization not found or no matching units
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  summary: Organization not found
                  value:
                    metaData:
                      apiLogId: 547743
                      timeStamp: '2026-07-21T10:43:00'
                      resource: GetDataUnit (1218)
                      method: GET
                      requestUrl: >-
                        https://se-webservice.apps.creditsafe.com/getdataunit?searchnumber=9999999999
                    error:
                      code: '15'
                      text: Ingen träff
                      detail: Söknumret får inte saknas eller vara tomt
                noMatchingUnits:
                  summary: No units match filter criteria
                  value:
                    metaData:
                      apiLogId: 547744
                      timeStamp: '2026-07-21T10:44:00'
                      resource: GetDataUnit (1218)
                      method: GET
                      requestUrl: >-
                        https://se-webservice.apps.creditsafe.com/getdataunit?searchnumber=5565144408&officetype=9
                    error:
                      code: C55
                      text: Saknas arbetsställen
                      detail: Saknas arbetsställen som motsvarar inmatade parametrar
        '504':
          description: Gateway timeout - Request took longer than 30 seconds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /getdataunit/health:
    get:
      tags:
        - Health Check
      operationId: healthCheck
      summary: Health check
      description: Returns the health status of the service.
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthCheckResponse'
              example:
                status: healthy
                service: GetDataUnit (1218)
                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:
    CodeDescType:
      type: object
      description: Code and description pair.
      properties:
        code:
          type: string
          description: Code value.
        description:
          type: string
          description: Description for the code.
    Address:
      type: object
      description: Address details.
      properties:
        address:
          type: string
          description: Street address.
        postNr:
          type: string
          description: Postal code.
        city:
          type: string
          description: City name.
        countryCode:
          type: string
          description: Country code (ISO 3166-1 alpha-2).
    Phone:
      type: object
      description: Phone number details.
      properties:
        countryCode:
          type: string
          description: Country code for the phone number.
        areaCode:
          type: string
          description: Area code for the phone number.
        number:
          type: string
          description: Phone number.
    Fax:
      type: object
      description: Fax number details.
      properties:
        countryCode:
          type: string
          description: Country code for the fax number.
        areaCode:
          type: string
          description: Area code for the fax number.
        number:
          type: string
          description: Fax number.
    GetDataUnitRestResponse:
      type: object
      description: Company unit data item within the report array.
      properties:
        name:
          type: string
          description: Company Unit Name
        officeType:
          $ref: '#/components/schemas/CodeDescType'
        status:
          $ref: '#/components/schemas/CodeDescType'
        employeeRange:
          type: string
          description: Employee range for the company.
        industry:
          $ref: '#/components/schemas/CodeDescType'
        visitingAddress:
          $ref: '#/components/schemas/Address'
        mailingAddress:
          $ref: '#/components/schemas/Address'
        phone:
          $ref: '#/components/schemas/Phone'
        fax:
          $ref: '#/components/schemas/Fax'
        cfar:
          type: string
          description: Company CFAR code.
    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
            timeStamp:
              type: string
              format: date-time
              description: The exact time when the request was processed
            resource:
              type: string
              description: Which service delivered the response
              example: GetDataUnit (1218)
            method:
              type: string
              description: The HTTP method used for the request
              example: GET
            requestUrl:
              type: string
              description: The complete URL of the request
        error:
          type: object
          description: Error details
          required:
            - code
            - text
          properties:
            code:
              type: string
              description: Error code identifier
              example: '15'
            text:
              type: string
              description: Error message text (language depends on language parameter)
              example: Ingen träff
            detail:
              type: string
              description: >-
                Additional error details. This property is optional and may be
                omitted entirely when no additional context is available.
              example: Söknumret får inte saknas eller vara tomt
    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: []
