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