openapi: 3.1.0
info:
  title: Get Signatory
  x-metadata:
    status: published
    tags:
      - Sweden
  description: >-
    The GetSignatory REST API enables you to retrieve information about
    authorized signatories  for a Swedish company. This service identifies who
    is authorized to sign for the company and  provides possible signing
    combinations (up to 5,000), including administrative signatories.
  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: Signatory Retrieval
    description: Operations for retrieving company signatory information
  - name: Health Check
    description: Service health check endpoint
paths:
  /getsignatory:
    get:
      tags:
        - Signatory Retrieval
      operationId: getSignatory
      summary: Retrieve company signatory information
      description: >-
        Retrieves signatory information for a company based on search
        parameters. Returns 404 if not found or 400 for invalid input.
      parameters:
        - name: searchnumber
          in: query
          required: true
          description: Organization number (10 digits)
          schema:
            type: string
            maxLength: 10
        - name: language
          in: query
          required: false
          description: The language for the response. Defaults to 'en'.
          schema:
            type: string
            enum:
              - en
              - sv
        - 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 signatory information and metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignatoryResponseLocal'
        '400':
          description: >
            Bad Request - Invalid parameters. Common causes include: invalid
            language parameter (R1)  or missing/empty searchnumber (15).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidLanguage:
                  summary: Invalid language parameter
                  value:
                    metaData:
                      apiLogId: 547748
                      timeStamp: '2026-07-21T10:48:00'
                      resource: GetSignatory (1227)
                      method: GET
                      requestUrl: >-
                        https://se-webservice.apps.creditsafe.com/getsignatory?searchnumber=5565144408&language=xx
                    error:
                      code: R1
                      text: The language must be either en (default) or sv (swedish)
                missingSearchNumber:
                  summary: Missing or empty searchnumber
                  value:
                    metaData:
                      apiLogId: 547749
                      timeStamp: '2026-07-21T10:49:00'
                      resource: GetSignatory (1227)
                      method: GET
                      requestUrl: >-
                        https://se-webservice.apps.creditsafe.com/getsignatory?searchnumber=
                    error:
                      code: '15'
                      text: Ingen träff
                      detail: Söknumret får inte saknas eller vara tomt
        '403':
          description: >
            Forbidden - Service access denied. Common causes include:
            insufficient credits/balance (error code 7),  service not enabled
            for user (code 8), or no access to the company type (code 17).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                noAccess:
                  summary: No access to service
                  value:
                    metaData:
                      apiLogId: 547750
                      timeStamp: '2026-07-21T10:50:00'
                      resource: GetSignatory (1227)
                      method: GET
                      requestUrl: >-
                        https://se-webservice.apps.creditsafe.com/getsignatory?searchnumber=5565144408
                    error:
                      code: '7'
                      text: Ej tillgång till tjänsten
                      detail: Ditt kundkonto har inte tjänsten GetSignatory (1227)
                quotaExhausted:
                  summary: Report quota exhausted
                  value:
                    metaData:
                      apiLogId: 547751
                      timeStamp: '2026-07-21T10:51:00'
                      resource: GetSignatory (1227)
                      method: GET
                      requestUrl: >-
                        https://se-webservice.apps.creditsafe.com/getsignatory?searchnumber=5565144408
                    error:
                      code: '8'
                      text: Rapporter/poäng slut
                      detail: >-
                        Inga kvarvarande rapporter för kontot eller användaren
                        till tjänsten GetSignatory (1227)
                companyTypeAccess:
                  summary: No access to this company type
                  value:
                    metaData:
                      apiLogId: 547752
                      timeStamp: '2026-07-21T10:52:00'
                      resource: GetSignatory (1227)
                      method: GET
                      requestUrl: >-
                        https://se-webservice.apps.creditsafe.com/getsignatory?searchnumber=5565144408
                    error:
                      code: '17'
                      text: Ej tillgång till denna företagstyp
                      detail: Ej tillgång till denna företagstyp – AB
        '404':
          description: >
            Not Found - No company found for the supplied organization number,
            or no signatory data exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  summary: Company not found or no signatory data
                  value:
                    metaData:
                      apiLogId: 547753
                      timeStamp: '2026-07-21T10:53:00'
                      resource: GetSignatory (1227)
                      method: GET
                      requestUrl: >-
                        https://se-webservice.apps.creditsafe.com/getsignatory?searchnumber=9999999999
                    error:
                      code: '15'
                      text: Ingen träff
        '500':
          description: >
            Internal Server Error - Unexpected error occurred. Retry the request
            later; contact Creditsafe if the problem persists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internalError:
                  summary: Internal server error
                  value:
                    metaData:
                      apiLogId: 547754
                      timeStamp: '2026-07-21T10:54:00'
                      resource: GetSignatory (1227)
                      method: GET
                      requestUrl: >-
                        https://se-webservice.apps.creditsafe.com/getsignatory?searchnumber=5565144408
                    error:
                      code: '14'
                      text: Ett fel har inträffat, försök igen senare
        '504':
          description: Gateway timeout - Request took longer than 30 seconds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /getsignatory/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: GetSignatory (1227)
                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:
    Position:
      type: object
      description: Board position details.
      properties:
        roleCode:
          type: integer
          description: Role code for board position.
        roleName:
          type: string
          description: Role name for board position.
    Person:
      type: object
      description: Represents a person that is allowed to sign for the company.
      properties:
        name:
          type: string
          description: Name of the signatory.
        positions:
          type: array
          description: Board function(s)/position(s) of the signatory.
          items:
            $ref: '#/components/schemas/Position'
        personalNumber:
          type: string
          description: Person number checked for signing rights.
    SignatoryResponseLocal:
      type: object
      description: >-
        Complete signatory response with metadata wrapper. The response includes
        signatory data  in a report object and audit metadata for tracking and
        support purposes.
      required:
        - metaData
        - report
      properties:
        metaData:
          type: object
          description: Audit metadata for the API call
          required:
            - apiLogId
            - timeStamp
            - resource
            - method
            - requestUrl
          properties:
            apiLogId:
              type: integer
              description: >-
                Unique identifier for the API call. Include this when contacting
                Creditsafe support.
              example: 233255
            timeStamp:
              type: string
              format: date-time
              description: ISO 8601 timestamp when the request was processed
              example: '2025-10-06T06:12:03'
            resource:
              type: string
              description: Service identifier
              example: GetSignatory (1227)
            method:
              type: string
              description: HTTP method used
              enum:
                - GET
              example: GET
            requestUrl:
              type: string
              description: Full URL of the API request
              example: >-
                https://se-webservice.apps.creditsafe.com/getsignatory?searchnumber=5565144408
        report:
          type: object
          description: Signatory information for the company.
          required:
            - companyId
            - coverage
          properties:
            companyId:
              type: string
              description: Company organization number
              example: '5565144408'
            coverage:
              type: string
              description: >-
                Coverage level of the signatory information: 'complete' (all
                signatories found),  'partial' (some information available), or
                'none' (no signatory data available)
              enum:
                - complete
                - partial
                - none
              example: complete
            adminSign:
              type: array
              description: >-
                Array of persons authorized to sign for the company only in
                administrative matters.  Each signing combination is an array of
                Person objects.
              items:
                type: array
                items:
                  $ref: '#/components/schemas/Person'
            combinations:
              type: array
              description: >-
                Possible signing combinations for the company. Each combination
                is an array of Person  objects who must sign together.
              items:
                type: array
                items:
                  $ref: '#/components/schemas/Person'
    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: GetSignatory (1227)
            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: []
