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.
Before you begin, ensure you have:
- ✅ Active Creditsafe account with API access
- ✅ SPAR authorization from Swedish Tax Agency (see SPAR Access Authorization)
- ✅ SPAR credentials configured with Creditsafe
- ✅ API credentials for authentication
- ✅ Development environment with HTTPS capability
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.
Before making SPAR requests, obtain an authentication token:
POST https://connect.creditsafe.com/v1/authenticate
Content-Type: application/json
{
"username": "your-username",
"password": "your-password"
}Response:
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Tokens are valid for 1 hour. Implement token caching and refresh logic to avoid unnecessary authentication requests.
Best practices:
- Cache the token and its expiration time
- Refresh the token proactively (e.g., after 55 minutes)
- Don't authenticate before every SPAR request
- Store tokens securely (encrypted at rest, never in logs)
GET https://se-webservice.apps.creditsafe.com/spar?searchnumber=199901011234&transactionid=TEST-001
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...{
"personId": "199901011234",
"namn": [
{
"fornamn": "ANNA MARIA",
"efternamn": "ANDERSSON",
"tilltalsnamn": "MARIA",
"aviseringsnamn": "Anna Maria Andersson"
}
],
"persondetaljer": [
{
"kon": "K",
"fodelseDatum": "1999-01-01"
}
],
"folkbokforingsadress": [
{
"utdelningsadress1": "ÖRNGATAN 45",
"postnummer": "11522",
"postort": "STOCKHOLM"
}
],
"metaData": {
"apiLogId": "abc123...",
"timeStamp": "2025-09-15T13:27:14.3794136Z"
}
}Focus on the most commonly needed fields:
// Example: Extract essential person information
const person = {
id: response.personId,
name: response.namn[0].aviseringsnamn,
givenName: response.namn[0].tilltalsnamn,
gender: response.persondetaljer[0].kon,
birthDate: response.persondetaljer[0].fodelseDatum,
address: {
street: response.folkbokforingsadress[0].utdelningsadress1,
postalCode: response.folkbokforingsadress[0].postnummer,
city: response.folkbokforingsadress[0].postort
}
};import requests
import time
def get_spar_data(search_number, token, max_retries=3):
"""
Retrieve SPAR data with proper error handling and retries.
"""
url = "https://se-webservice.apps.creditsafe.com/spar"
headers = {"Authorization": f"Bearer {token}"}
params = {"searchnumber": search_number}
for attempt in range(max_retries):
try:
response = requests.get(url, headers=headers, params=params, timeout=30)
if response.status_code == 200:
return {"success": True, "data": response.json()}
elif response.status_code == 404:
# Person not found - this is a valid business outcome
return {"success": False, "error": "NOT_FOUND", "message": "Person not found in SPAR"}
elif response.status_code == 403:
# Authentication issue - need new token
return {"success": False, "error": "AUTH_REQUIRED", "message": "Token expired or invalid"}
elif response.status_code == 500:
error_data = response.json()
error_code = error_data.get("errorCode", "")
# SPAR service unavailable - retry
if error_code in ["EX1", "EX2"]:
if attempt < max_retries - 1:
wait_time = 2 ** attempt # Exponential backoff
time.sleep(wait_time)
continue
else:
return {"success": False, "error": "SPAR_UNAVAILABLE",
"message": "SPAR service temporarily unavailable"}
# Other server error
return {"success": False, "error": "SERVER_ERROR",
"message": error_data.get("errorDescription", "Unknown error"),
"apiLogId": error_data.get("metaData", {}).get("apiLogId")}
else:
error_data = response.json() if response.content else {}
return {"success": False, "error": "API_ERROR",
"message": f"HTTP {response.status_code}: {error_data.get('errorDescription', 'Unknown error')}"}
except requests.exceptions.Timeout:
if attempt < max_retries - 1:
time.sleep(2 ** attempt)
continue
return {"success": False, "error": "TIMEOUT", "message": "Request timed out"}
except Exception as e:
return {"success": False, "error": "EXCEPTION", "message": str(e)}
return {"success": False, "error": "MAX_RETRIES", "message": "Maximum retry attempts exceeded"}| Scenario | HTTP Status | Action |
|---|---|---|
| Person not found | 404 | Log as business outcome, don't retry |
| Token expired | 403 | Refresh token and retry |
| SPAR unavailable (EX1, EX2) | 500 | Retry with exponential backoff |
| Rate limit exceeded | 429 | Wait and retry, implement throttling |
| Invalid credentials | 401 | Alert operations, don't retry |
| Relation not authorized | 403 (error 17) | Remove relation parameter or request authorization |
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.
Consumer Monitoring is ideal for:
- Credit monitoring: Track address changes for ongoing credit relationships
- Fraud prevention: Detect unusual changes in consumer information
- Communication management: Stay updated on address changes
- Compliance: Maintain current information for regulatory requirements
- Risk management: Monitor for deregistration (emigration/death)
Contact your Creditsafe account manager for more information about Consumer Monitoring integration options.
- Technical integration support: integration@creditsafe.se
- SPAR authorization questions: Your Creditsafe Account Manager
- Regulatory compliance: Skatteverket or your legal counsel
- API documentation: This documentation portal