openapi: 3.1.0
info:
  title: SPAR Consumer Search
  x-metadata:
    status: published
    tags:
      - Sweden
  description: >-
    Using Creditsafe's v2 REST API connected to SPAR (Statens
    personadressregister),  you can access and retrieve information on all
    residents of Sweden—including individuals  under the age of 16. This
    functionality complements our other APIs and is designed to  work seamlessly
    with Consumer Monitoring for daily updates on your customer base.
  version: 2.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: SPAR
    description: SPAR person data retrieval operations
  - name: Health Check
    description: Service health check endpoint
paths:
  /spar:
    get:
      tags:
        - SPAR
      operationId: getSparData
      summary: Retrieve SPAR person information
      description: >-
        Retrieves detailed information from SPAR (Statens personadressregister)
        for a person  based on their personal identity number. The information
        returned depends on the  authorization level granted by SPAR, but at
        minimum includes status, first name,  given name, last name, gender, and
        address.


        **Note:** This service retrieves data from SPAR's external system.
        Creditsafe cannot  guarantee uptime or intervene in the event of
        downtime caused by issues on SPAR's side.


        **Response Field Behavior:** Many response fields may be omitted or null
        at runtime  depending on SPAR authorization level, data availability,
        and the person's registration  status. Clients should handle missing
        fields gracefully.
      parameters:
        - name: searchnumber
          in: query
          required: true
          description: The requested person number (12 digits)
          schema:
            type: string
            maxLength: 12
            pattern: ^\d{12}$
            example: '199901011234'
        - name: relation
          in: query
          required: false
          description: >-
            Optional. Inclusion of relation data. Default value is false. 
            **Important:** Passing a true value requires access rights to see
            relation data.  Without proper authorization, requests with
            relation=true will return error code EX1 or 17.
          schema:
            type: boolean
            default: false
        - name: usespartest
          in: query
          required: false
          description: >-
            Optional. When true, directs the request to SPAR's test environment
            instead of live data.  Default value is false. On sandbox hosts,
            this parameter controls whether to query the  SPAR test API (true)
            or use the local sandbox database (false). On production hosts, 
            this parameter routes to either SPAR live (false) or SPAR test
            (true) environments.
          schema:
            type: boolean
            default: false
        - 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: INV-12345
        - name: language
          in: query
          required: false
          description: >-
            Optional. Sets the language of the response. For this service it
            only affects  error responses. Available languages: sv (Swedish) or
            en (English). Default is en.
          schema:
            type: string
            enum:
              - en
              - sv
            default: en
            example: sv
      responses:
        '200':
          description: >
            Successful response with SPAR person data. Fields may be omitted or
            null depending on  SPAR authorization level, data availability, and
            registration status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonSokResponseModel'
        '400':
          description: >
            Bad Request - Invalid parameters. Common causes include: invalid
            language parameter (R1),  invalid person number format (EX2), or
            missing searchnumber (15).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalidLanguage:
                  summary: Invalid language parameter
                  value:
                    metaData:
                      apiLogId: 542901
                      timeStamp: '2026-07-15T14:27:00'
                      resource: SPAR Consumer (1231)
                      method: GET
                      requestUrl: >-
                        https://se-webservice.apps.creditsafe.com/spar?searchnumber=199901011234&language=xx
                    error:
                      code: R1
                      text: The language must be either en (default) or sv (swedish)
                    report: null
                invalidPersonNumber:
                  summary: Invalid person number format
                  value:
                    metaData:
                      apiLogId: 542902
                      timeStamp: '2026-07-15T14:28:00'
                      resource: SPAR Consumer (1231)
                      method: GET
                      requestUrl: >-
                        https://se-webservice.apps.creditsafe.com/spar?searchnumber=invalid
                    error:
                      code: EX2
                      text: Ogiltigt personnummer
                      detail: Felaktigt format på personnummer
                    report: null
        '401':
          description: >
            Unauthorized - SPAR credentials are missing, invalid, or the
            assignment ID is incorrect (EX1).  This may also indicate issues
            with SPAR authorization or undantag (exception) responses from SPAR.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                sparCredentials:
                  summary: SPAR credentials error
                  value:
                    metaData:
                      apiLogId: 542903
                      timeStamp: '2026-07-15T14:29:00'
                      resource: SPAR Consumer (1231)
                      method: GET
                      requestUrl: >-
                        https://se-webservice.apps.creditsafe.com/spar?searchnumber=199901011234
                    error:
                      code: EX1
                      text: Åtkomst till SPAR tjänsten
                      detail: SPAR uppdrags id felaktigt
                    report: null
        '403':
          description: >
            Forbidden - Service access denied. Common causes include:
            insufficient credits/balance (error code 7)  or service not enabled
            for user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                insufficientCredits:
                  summary: Insufficient credits or service not enabled
                  value:
                    metaData:
                      apiLogId: 542904
                      timeStamp: '2026-07-15T14:30:00'
                      resource: SPAR Consumer (1231)
                      method: GET
                      requestUrl: >-
                        https://se-webservice.apps.creditsafe.com/spar?searchnumber=199901011234
                    error:
                      code: '7'
                      text: Ej tillgång till tjänsten
                      detail: Ditt kundkonto har inte tjänsten SPAR Consumer (1231)
                    report: null
        '404':
          description: >
            Not Found - Person not found in SPAR (error code 15), or
            searchnumber parameter is missing/empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                personNotFound:
                  summary: Person not found in SPAR
                  value:
                    metaData:
                      apiLogId: 542905
                      timeStamp: '2026-07-15T14:31:00'
                      resource: SPAR Consumer (1231)
                      method: GET
                      requestUrl: >-
                        https://se-webservice.apps.creditsafe.com/spar?searchnumber=199901011234
                    error:
                      code: '15'
                      text: Ingen träff
                    report: null
        '500':
          description: >
            Internal Server Error - Unexpected error from SPAR or internal
            processing failure (error code 14 or EX3).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                internalError:
                  summary: Internal server error
                  value:
                    metaData:
                      apiLogId: 542906
                      timeStamp: '2026-07-15T14:32:00'
                      resource: SPAR Consumer (1231)
                      method: GET
                      requestUrl: >-
                        https://se-webservice.apps.creditsafe.com/spar?searchnumber=199901011234
                    error:
                      code: '14'
                      text: Ett fel har inträffat, försök igen senare
                    report: null
  /spar/health:
    get:
      tags:
        - Health Check
      operationId: healthCheck
      summary: Service health check
      description: >-
        Lightweight endpoint to verify that the SPAR 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 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: SPAR Consumer (1231)
                  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: SPAR Consumer (1231)
                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:
    AviseringPostTypeModel:
      type: object
      description: >-
        SPAR person data record. Fields may be omitted or null depending on SPAR
        authorization level,  data availability, and the person's registration
        status.
      properties:
        personId:
          type: object
          description: Person identifier with ID number and type
          properties:
            idNummer:
              type: string
              description: Personal identity number (12 digits)
              example: '194411155858'
            typ:
              type: string
              description: ID type (typically PERSONNUMMER)
              example: PERSONNUMMER
        sekretessmarkering:
          type: object
          description: Secrecy marking details
          properties:
            sattAvSPAR:
              type:
                - string
                - 'null'
              description: Set by SPAR indicator
            value:
              type: string
              description: Secrecy marking value (JA/NEJ)
              example: NEJ
        sekretessDatum:
          type:
            - string
            - 'null'
          format: date-time
          description: Date of secrecy marking
        skyddadFolkbokforing:
          type: string
          description: Protected population registration (JA/NEJ)
          example: NEJ
        skyddadFolkbokforingDatum:
          type:
            - string
            - 'null'
          format: date-time
          description: Date of protected population registration
        senasteAndringSPAR:
          type: string
          format: date-time
          description: Date of latest change in SPAR
          example: '2021-09-25T00:00:00'
        summeradInkomst:
          type:
            - string
            - 'null'
          description: Summed income
        inkomstAr:
          type:
            - string
            - 'null'
          description: Income year
        namn:
          type: array
          description: Array of name records with validity periods
          items:
            type: object
            properties:
              datumFrom:
                type: string
                format: date-time
                description: Valid from date
                example: '2021-09-25T00:00:00'
              datumTill:
                type: string
                format: date-time
                description: Valid until date (9999-12-31T00:00:00 for active records)
                example: '9999-12-31T00:00:00'
              aviseringsnamn:
                type:
                  - string
                  - 'null'
                description: Full notification name
              fornamn:
                type: string
                description: First name(s)
                example: Adam
              tilltalsnamn:
                type:
                  - string
                  - 'null'
                description: Given name (calling name)
              mellannamn:
                type:
                  - string
                  - 'null'
                description: Middle name
              efternamn:
                type: string
                description: Last name
                example: Efternamn1130
        persondetaljer:
          type: array
          description: Array of person detail records with validity periods
          items:
            type: object
            properties:
              datumFrom:
                type: string
                format: date-time
                description: Valid from date
              datumTill:
                type: string
                format: date-time
                description: Valid until date
              sekretessmarkering:
                type: object
                properties:
                  sattAvSPAR:
                    type:
                      - string
                      - 'null'
                  value:
                    type: string
                    example: NEJ
              skyddadFolkbokforing:
                type: string
                description: Protected population registration
              avregistreringsorsakKod:
                type:
                  - string
                  - 'null'
                description: Deregistration reason code
              avregistreringsdatum:
                type:
                  - string
                  - 'null'
                format: date-time
                description: Deregistration date
              avlidendatum:
                type:
                  - string
                  - 'null'
                format: date-time
                description: Date of death
              antraffadDodDatum:
                type:
                  - string
                  - 'null'
                format: date-time
                description: Date found deceased
              fodelsedatum:
                type: string
                format: date-time
                description: Date of birth
                example: '1944-11-15T00:00:00'
              fodelselanKod:
                type:
                  - string
                  - 'null'
                description: Birth county code
              fodelseforsamling:
                type:
                  - string
                  - 'null'
                description: Birth parish
              kon:
                type: string
                description: Gender (MAN/KVINNA)
                example: MAN
              svenskMedborgare:
                type:
                  - string
                  - 'null'
                description: Swedish citizen indicator
              hanvisning:
                type: array
                description: Reference to new or previous ID number
                items:
                  type: object
              snStatus:
                type:
                  - string
                  - 'null'
                description: SN status
              snTilldelningsdatum:
                type:
                  - string
                  - 'null'
                format: date-time
                description: SN assignment date
              snPreliminartVilandeforklaringsdatum:
                type:
                  - string
                  - 'null'
                format: date-time
                description: SN preliminary dormancy declaration date
              snFornyelsedatum:
                type:
                  - string
                  - 'null'
                format: date-time
                description: SN renewal date
              snVilandeorsak:
                type:
                  - string
                  - 'null'
                description: SN dormancy reason
              snVilandeforklaringsdatum:
                type:
                  - string
                  - 'null'
                format: date-time
                description: SN dormancy declaration date
              snAvlidendatum:
                type:
                  - string
                  - 'null'
                format: date-time
                description: SN deceased date
        folkbokforing:
          type: array
          description: Array of population registration records with validity periods
          items:
            type: object
            properties:
              datumFrom:
                type: string
                format: date-time
                description: Valid from date
              datumTill:
                type: string
                format: date-time
                description: Valid until date
              folkbokfordLanKod:
                type: string
                description: Registered county code
                example: '01'
              folkbokfordKommunKod:
                type: string
                description: Registered municipality code
                example: '25'
              hemvist:
                type: string
                description: Domicile status
                example: Skrivenpåadressen
              folkbokforingsdatum:
                type: string
                format: date-time
                description: Population registration date
                example: '1997-05-01T00:00:00'
              distriktKod:
                type: string
                description: District code
                example: '215006'
        folkbokforingsadress:
          type: array
          description: Array of population registration address records
          items:
            type: object
            properties:
              svenskAdress:
                type:
                  - object
                  - 'null'
                description: Swedish address
                properties:
                  datumFrom:
                    type: string
                    format: date-time
                    description: Valid from date
                  datumTill:
                    type: string
                    format: date-time
                    description: Valid until date
                  careOf:
                    type:
                      - string
                      - 'null'
                    description: Care of (c/o)
                  utdelningsadress1:
                    type:
                      - string
                      - 'null'
                    description: Delivery address line 1
                  utdelningsadress2:
                    type:
                      - string
                      - 'null'
                    description: Delivery address line 2
                    example: Gatan229 2
                  postNr:
                    type: string
                    description: Postal code
                    example: '17962'
                  postort:
                    type: string
                    description: Postal area
                    example: STENHAMRA
        sarskildPostadress:
          type: array
          description: Array of special postal address records
          items:
            type: object
            properties:
              internationellAdress:
                type:
                  - object
                  - 'null'
                description: International address
                properties:
                  datumFrom:
                    type: string
                    format: date-time
                    description: Valid from date
                  datumTill:
                    type: string
                    format: date-time
                    description: Valid until date
                  utdelningsadress1:
                    type:
                      - string
                      - 'null'
                    description: Delivery address line 1
                  utdelningsadress2:
                    type:
                      - string
                      - 'null'
                    description: Delivery address line 2
                    example: UTLANDOMRÅDE
                  utdelningsadress3:
                    type:
                      - string
                      - 'null'
                    description: Delivery address line 3
                  land:
                    type: string
                    description: Country
                    example: MONACO
              svenskAdress:
                type:
                  - object
                  - 'null'
                description: Swedish special postal address
        utlandsadress:
          type:
            - array
            - 'null'
          description: Array of foreign address records
          items:
            type: object
        kontaktadress:
          type:
            - array
            - 'null'
          description: Array of contact address records
          items:
            type: object
        relation:
          type: array
          description: >-
            Array of relation records (requires special authorization via
            relation=true parameter)
          items:
            type: object
            properties:
              datumFrom:
                type: string
                format: date-time
                description: Valid from date
              datumTill:
                type: string
                format: date-time
                description: Valid until date
              relationstyp:
                type: string
                description: Relation type
                example: MAKEMAKAREGISTRERADPARTNER
              idNummer:
                type: string
                description: Related person's ID number
                example: '195401038145'
              fornamn:
                type:
                  - string
                  - 'null'
                description: Related person's first name
              mellannamn:
                type:
                  - string
                  - 'null'
                description: Related person's middle name
              efternamn:
                type:
                  - string
                  - 'null'
                description: Related person's last name
              fodelsetid:
                type: string
                format: date-time
                description: Related person's birth date
                example: '1954-01-03T00:00:00'
              avregistreringsorsakKod:
                type:
                  - string
                  - 'null'
                description: Deregistration reason code
              avregistreringsdatum:
                type:
                  - string
                  - 'null'
                format: date-time
                description: Deregistration date
              avlidendatum:
                type:
                  - string
                  - 'null'
                format: date-time
                description: Date of death
        fastighet:
          type:
            - array
            - 'null'
          description: Array of property records
          items:
            type: object
    PersonSokResponseModel:
      type: object
      description: SPAR person search response with metadata wrapper.
      required:
        - metaData
        - error
      properties:
        metaData:
          type: object
          description: >-
            Metadata section containing request information for tracing and
            troubleshooting
          required:
            - apiLogId
            - timeStamp
            - resource
            - method
            - requestUrl
          properties:
            apiLogId:
              type: integer
              description: >-
                Unique identifier for the Creditsafe API log. Refer to this ID
                when contacting support
              example: 542900
            timeStamp:
              type: string
              format: date-time
              description: The exact time when the request was processed by Creditsafe
              example: '2026-07-15T14:26:33'
            resource:
              type: string
              description: Indicates which service delivered the report
              example: SPAR Consumer (1231)
            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
        response:
          type: array
          description: >-
            Array of SPAR person data records. Note that the top-level object is
            called 'response' in SPAR, unlike 'report' in other Swedish APIs.
          items:
            $ref: '#/components/schemas/AviseringPostTypeModel'
        error:
          type: 'null'
          description: Always null in successful responses
    Error:
      type: object
      description: >-
        Standard error response format for SPAR API. Error responses include
        metaData, error, and report (null).
      required:
        - metaData
        - error
        - report
      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: SPAR Consumer (1231)
            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 container
          required:
            - code
            - text
          properties:
            code:
              type: string
              description: >-
                Error code identifying the specific error. Common codes include:
                R1 (invalid language),  EX1 (SPAR credentials/authorization),
                EX2 (invalid person number format), EX3 (unexpected SPAR
                error),  7 (insufficient credits), 8 (no reports remaining), 14
                (internal error), 15 (not found).
              example: '15'
            text:
              type: string
              description: >-
                Human-readable error message in the requested language (en or
                sv)
              example: Ingen träff
            detail:
              type:
                - string
                - 'null'
              description: >-
                Additional error details when available. May contain SPAR
                supplier error messages or  specific guidance. This property may
                be omitted entirely or set to null when no additional details
                are available.
              example: Söknumret får inte saknas eller vara tomt
        report:
          type: 'null'
          description: Always null in error responses
      example:
        metaData:
          apiLogId: 547640
          timeStamp: '2026-07-21T09:15:00'
          resource: SPAR Consumer (1231)
          method: GET
          requestUrl: >-
            https://se-webservice.apps.creditsafe.com/spar?searchnumber=123456789012
        error:
          code: '15'
          text: Ingen träff
        report: null
security:
  - bearerToken: []
