{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-country-apis-catalog/product-catalog/se/spar/sidebars.yaml","current-catalog-info":"current-catalog-info-/country-apis-catalog/product-catalog/se/spar/openapi"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Step-by-Step Integration Guide","llmstxt":{"hide":true}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"step-by-step-integration-guide","__idx":0},"children":["Step-by-Step Integration Guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide walks you through integrating the SPAR API into your application, from initial setup through production usage. It also covers integration with Creditsafe's Consumer Monitoring service for ongoing updates."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before you begin, ensure you have:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["✅ Active Creditsafe account with API access"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["✅ SPAR authorization from Swedish Tax Agency (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/country-apis-catalog/product-catalog/se/spar/documentation/access"},"children":["SPAR Access Authorization"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["✅ SPAR credentials configured with Creditsafe"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["✅ API credentials for authentication"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["✅ Development environment with HTTPS capability"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"integration-workflow","__idx":2},"children":["Integration Workflow"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart TD\n A[Start] --> B[Obtain Authentication Token]\n B --> C[Make SPAR Request]\n C --> D{Response OK?}\n D -->|Yes| E[Process Person Data]\n D -->|No| F{Error Code?}\n F -->|Auth Error| B\n F -->|Not Found| G[Handle Not Found]\n F -->|SPAR Unavailable| H[Retry Later]\n F -->|Other Error| I[Log & Alert]\n E --> J[Store Data]\n J --> K{Setup Monitoring?}\n K -->|Yes| L[Add to Consumer Monitoring]\n K -->|No| M[End]\n L --> M\n G --> M\n H --> C\n I --> M\n","diagramHtml":"

Yes

No

Auth Error

Not Found

SPAR Unavailable

Other Error

Yes

No

Start

Obtain Authentication Token

Make SPAR Request

Response OK?

Process Person Data

Error Code?

Handle Not Found

Retry Later

Log & Alert

Store Data

Setup Monitoring?

Add to Consumer Monitoring

End

","diagramHtmlDark":"

Yes

No

Auth Error

Not Found

SPAR Unavailable

Other Error

Yes

No

Start

Obtain Authentication Token

Make SPAR Request

Response OK?

Process Person Data

Error Code?

Handle Not Found

Retry Later

Log & Alert

Store Data

Setup Monitoring?

Add to Consumer Monitoring

End

"},"children":["flowchart TD\n A[Start] --> B[Obtain Authentication Token]\n B --> C[Make SPAR Request]\n C --> D{Response OK?}\n D -->|Yes| E[Process Person Data]\n D -->|No| F{Error Code?}\n F -->|Auth Error| B\n F -->|Not Found| G[Handle Not Found]\n F -->|SPAR Unavailable| H[Retry Later]\n F -->|Other Error| I[Log & Alert]\n E --> J[Store Data]\n J --> K{Setup Monitoring?}\n K -->|Yes| L[Add to Consumer Monitoring]\n K -->|No| M[End]\n L --> M\n G --> M\n H --> C\n I --> M\n"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Diagram summary (accessibility): Starting from authentication, obtain an authentication token and make a SPAR request. If the response is successful, process the person data, store it, and optionally subscribe to Consumer Monitoring. If unsuccessful, the error type determines the next action: authentication errors return to token retrieval, not-found errors are handled gracefully, SPAR unavailability triggers a retry, and other errors are logged and alerted."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-authentication-setup","__idx":3},"children":["Step 1: Authentication Setup"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"11-obtain-authentication-token","__idx":4},"children":["1.1 Obtain Authentication Token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before making SPAR requests, obtain an authentication token:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"POST https://connect.creditsafe.com/v1/authenticate\nContent-Type: application/json\n\n{\n \"username\": \"your-username\",\n \"password\": \"your-password\"\n}\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"12-store-token-securely","__idx":5},"children":["1.2 Store Token Securely"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Tokens are valid for 1 hour. Implement token caching and refresh logic to avoid unnecessary authentication requests."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Best practices:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cache the token and its expiration time"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Refresh the token proactively (e.g., after 55 minutes)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Don't authenticate before every SPAR request"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store tokens securely (encrypted at rest, never in logs)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-basic-spar-request","__idx":6},"children":["Step 2: Basic SPAR Request"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"21-make-your-first-request","__idx":7},"children":["2.1 Make Your First Request"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"GET https://se-webservice.apps.creditsafe.com/spar?searchnumber=199901011234&transactionid=TEST-001\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"22-process-the-response","__idx":8},"children":["2.2 Process the Response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"personId\": \"199901011234\",\n \"namn\": [\n {\n \"fornamn\": \"ANNA MARIA\",\n \"efternamn\": \"ANDERSSON\",\n \"tilltalsnamn\": \"MARIA\",\n \"aviseringsnamn\": \"Anna Maria Andersson\"\n }\n ],\n \"persondetaljer\": [\n {\n \"kon\": \"K\",\n \"fodelseDatum\": \"1999-01-01\"\n }\n ],\n \"folkbokforingsadress\": [\n {\n \"utdelningsadress1\": \"ÖRNGATAN 45\",\n \"postnummer\": \"11522\",\n \"postort\": \"STOCKHOLM\"\n }\n ],\n \"metaData\": {\n \"apiLogId\": \"abc123...\",\n \"timeStamp\": \"2025-09-15T13:27:14.3794136Z\"\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"23-extract-key-information","__idx":9},"children":["2.3 Extract Key Information"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Focus on the most commonly needed fields:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// Example: Extract essential person information\nconst person = {\n id: response.personId,\n name: response.namn[0].aviseringsnamn,\n givenName: response.namn[0].tilltalsnamn,\n gender: response.persondetaljer[0].kon,\n birthDate: response.persondetaljer[0].fodelseDatum,\n address: {\n street: response.folkbokforingsadress[0].utdelningsadress1,\n postalCode: response.folkbokforingsadress[0].postnummer,\n city: response.folkbokforingsadress[0].postort\n }\n};\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-error-handling","__idx":10},"children":["Step 3: Error Handling"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"31-implement-comprehensive-error-handling","__idx":11},"children":["3.1 Implement Comprehensive Error Handling"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import requests\nimport time\n\ndef get_spar_data(search_number, token, max_retries=3):\n \"\"\"\n Retrieve SPAR data with proper error handling and retries.\n \"\"\"\n url = \"https://se-webservice.apps.creditsafe.com/spar\"\n headers = {\"Authorization\": f\"Bearer {token}\"}\n params = {\"searchnumber\": search_number}\n \n for attempt in range(max_retries):\n try:\n response = requests.get(url, headers=headers, params=params, timeout=30)\n \n if response.status_code == 200:\n return {\"success\": True, \"data\": response.json()}\n \n elif response.status_code == 404:\n # Person not found - this is a valid business outcome\n return {\"success\": False, \"error\": \"NOT_FOUND\", \"message\": \"Person not found in SPAR\"}\n \n elif response.status_code == 403:\n # Authentication issue - need new token\n return {\"success\": False, \"error\": \"AUTH_REQUIRED\", \"message\": \"Token expired or invalid\"}\n \n elif response.status_code == 500:\n error_data = response.json()\n error_code = error_data.get(\"errorCode\", \"\")\n \n # SPAR service unavailable - retry\n if error_code in [\"EX1\", \"EX2\"]:\n if attempt < max_retries - 1:\n wait_time = 2 ** attempt # Exponential backoff\n time.sleep(wait_time)\n continue\n else:\n return {\"success\": False, \"error\": \"SPAR_UNAVAILABLE\", \n \"message\": \"SPAR service temporarily unavailable\"}\n \n # Other server error\n return {\"success\": False, \"error\": \"SERVER_ERROR\", \n \"message\": error_data.get(\"errorDescription\", \"Unknown error\"),\n \"apiLogId\": error_data.get(\"metaData\", {}).get(\"apiLogId\")}\n \n else:\n error_data = response.json() if response.content else {}\n return {\"success\": False, \"error\": \"API_ERROR\", \n \"message\": f\"HTTP {response.status_code}: {error_data.get('errorDescription', 'Unknown error')}\"}\n \n except requests.exceptions.Timeout:\n if attempt < max_retries - 1:\n time.sleep(2 ** attempt)\n continue\n return {\"success\": False, \"error\": \"TIMEOUT\", \"message\": \"Request timed out\"}\n \n except Exception as e:\n return {\"success\": False, \"error\": \"EXCEPTION\", \"message\": str(e)}\n \n return {\"success\": False, \"error\": \"MAX_RETRIES\", \"message\": \"Maximum retry attempts exceeded\"}\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"32-handle-specific-error-scenarios","__idx":12},"children":["3.2 Handle Specific Error Scenarios"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Scenario"},"children":["Scenario"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP Status"},"children":["HTTP Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Action"},"children":["Action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Person not found"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["404"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Log as business outcome, don't retry"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token expired"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["403"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Refresh token and retry"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["SPAR unavailable (EX1, EX2)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry with exponential backoff"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rate limit exceeded"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["429"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Wait and retry, implement throttling"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid credentials"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Alert operations, don't retry"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Relation not authorized"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["403 (error 17)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Remove ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["relation"]}," parameter or request authorization"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-integration-with-consumer-monitoring","__idx":13},"children":["Step 4: Integration with Consumer Monitoring"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SPAR API can be used in combination with Creditsafe's Consumer Monitoring service for ongoing updates. Consumer Monitoring provides automated alerts when monitored person data changes, allowing you to keep your records current without manual lookups."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Consumer Monitoring"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Consumer Monitoring is ideal for:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Credit monitoring"]},": Track address changes for ongoing credit relationships"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fraud prevention"]},": Detect unusual changes in consumer information"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Communication management"]},": Stay updated on address changes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Compliance"]},": Maintain current information for regulatory requirements"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Risk management"]},": Monitor for deregistration (emigration/death)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Contact your Creditsafe account manager for more information about Consumer Monitoring integration options."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"getting-help","__idx":14},"children":["Getting Help"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Technical integration support"]},": ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:integration@creditsafe.se"},"children":["integration@creditsafe.se"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SPAR authorization questions"]},": Your Creditsafe Account Manager"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Regulatory compliance"]},": Skatteverket or your legal counsel"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API documentation"]},": This documentation portal"]}]}]},"headings":[{"value":"Step-by-Step Integration Guide","id":"step-by-step-integration-guide","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Integration Workflow","id":"integration-workflow","depth":2},{"value":"Step 1: Authentication Setup","id":"step-1-authentication-setup","depth":2},{"value":"1.1 Obtain Authentication Token","id":"11-obtain-authentication-token","depth":3},{"value":"1.2 Store Token Securely","id":"12-store-token-securely","depth":3},{"value":"Step 2: Basic SPAR Request","id":"step-2-basic-spar-request","depth":2},{"value":"2.1 Make Your First Request","id":"21-make-your-first-request","depth":3},{"value":"2.2 Process the Response","id":"22-process-the-response","depth":3},{"value":"2.3 Extract Key Information","id":"23-extract-key-information","depth":3},{"value":"Step 3: Error Handling","id":"step-3-error-handling","depth":2},{"value":"3.1 Implement Comprehensive Error Handling","id":"31-implement-comprehensive-error-handling","depth":3},{"value":"3.2 Handle Specific Error Scenarios","id":"32-handle-specific-error-scenarios","depth":3},{"value":"Step 4: Integration with Consumer Monitoring","id":"step-4-integration-with-consumer-monitoring","depth":2},{"value":"Getting Help","id":"getting-help","depth":2}],"frontmatter":{"seo":{"title":"Step-by-Step Integration Guide"}},"lastModified":"2026-06-16T13:01:02.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/country-apis-catalog/product-catalog/se/spar/documentation/step-by-step-guide","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}