Case Processing System API documentation
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"43457039","collectionId":"7e93e738-0b30-4f79-a84a-0212b7cf9822","publishedId":"2sB3QDwsr1","public":true,"customColor":{"top-bar":"8750E5","right-sidebar":"303030","highlight":"29074A"},"publishDate":"2025-10-30T06:42:20.000Z"},"item":[{"name":"Introduction","item":[],"id":"55d23c44-691e-4293-ba9b-cb1390405e8e","description":"The Case Processing System API (CPS-API) enables clients to integrate directly with Intrum's debt collection platform. It facilitates the full lifecycle of debt-related operations such as case registration, invoice transactions, payment tracking, credit note processing, and portfolio reconciliation. This version (V1) is built with a focus on security, scalability, and clarity, incorporating client feedback and enhancement recommendations.
\nThis API is intended for:
\nClients of Intrum who want to automate debt registration and tracking
\nSystem integrators embedding Intrum’s debt processing capabilities into finance/ERP systems
\nDevelopers seeking to build robust, idempotent, and secure integrations with debt portfolios
\nINT (Integration): https://collection.test-api-intrum.ch/restServices/v1
PROD (Production): https://collection.api-intrum.ch/restServices/v1
All requests to the CPS-API must be made over HTTPS to ensure data confidentiality and integrity.
\nRequests that are not properly authenticated using OAuth 2.0 will be rejected with a 401 Unauthorized response. All endpoints are designed with security-first principles, enforcing token-based access and client isolation through dedicated credentials.
CPS-API V1 uses the OAuth 2.0 Client Credentials Grant to secure all API access. In this flow, applications authenticate using their client ID and client secret, and receive a time-limited access token to use in subsequent API requests.
\nThe client does not act on behalf of a user; it authenticates as itself. This ensures automation-friendly integration and robust server-to-server communication.
\nUpon onboarding, clients may receive:
\nRead/Write credentials: Grant access to all POST and GET endpoints. Suitable for systems that need to submit cases, report payments, and interact with the API in full.
\nRead-only credentials: Limit access to GET endpoints only. Ideal for systems that only need to query case statuses, invoice information, or fetch payment records for reporting or reconciliation.
\nUsing separate credentials enhances security by applying the principle of least privilege.
\nTokens must be retrieved by POSTing the credentials to one of the following URLs depending on environment:
\nIntegration (INT):
https://kc.intrum.com/auth/realms/debt-collection-api/protocol/openid-connect/token
Production (PROD):
https://kc.intrum.com/auth/realms/debt-collection-api/protocol/openid-connect/token
Token requests must include:
\ngrant_type=client_credentials
client_id=
client_secret=
If the token request is successful, the authorization server sends a response with the following properties:
\naccess_token: access token to use in authorization header
token_type: type of the token (in this case \"Bearer\")
expires_in: Seconds until expiration of access token. After this period, a new access token must be requested.
Once a token is retrieved, include it in the Authorization header of all requests:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\n\nFailure to include this header will result in a 401 Unauthorized error.
All endpoints require secure transport using HTTPS, and tokens must be renewed upon expiration (typically 300 seconds).
\n","auth":{"type":"noauth","isInherited":false},"_postman_id":"abd803cc-74ad-4bcc-8c80-9e1d9357065b"},{"name":"Errors","item":[],"id":"d10e73f5-cac5-437b-8b23-25803791fac4","description":"CPS-API V1 uses standard HTTP status codes to communicate the success or failure of each request. Clients should rely on these codes to implement robust error handling, retries, and user feedback mechanisms.
\nBy distinguishing these errors clearly, clients can optimize retry strategies and deliver helpful feedback to end users or system logs.
\n","auth":{"type":"noauth","isInherited":false},"_postman_id":"d10e73f5-cac5-437b-8b23-25803791fac4"},{"name":"Pagination","item":[],"id":"cbb3b854-c10a-4180-93af-364ef85e976e","description":"CPS-API V1 implements cursor-based pagination to efficiently manage and navigate large datasets. Instead of traditional page numbers, cursors like startingAfter and endingBefore are used to indicate the position in the dataset from which the next batch of results should be returned.
This approach ensures reliable, deterministic paging even in dynamic datasets where new records might be added or updated between requests. It avoids the common pitfalls of offset-based pagination, such as missing or duplicated entries.
\nCursor-based pagination is particularly well-suited for automated polling and data synchronization between systems.
\nhasMoreThe response body includes a field named hasMore, which is a Boolean flag indicating whether more data is available beyond the current result set.
This flag allows clients to determine whether they should issue additional requests using startingAfter or endingBefore to continue retrieving data.
If hasMore is false, the client has reached the end of the available data.
Always set a reasonable limit to control batch sizes and minimize latency.
Use startingAfter in combination with the ID of the last item received to safely paginate forward.
Avoid using both startingAfter and endingBefore in the same request.
Monitor hasMore to know when to stop paginating.
Following these patterns allows clients to build stable, incremental sync logic across large or frequently updated datasets.
\n","auth":{"type":"noauth","isInherited":false},"_postman_id":"cbb3b854-c10a-4180-93af-364ef85e976e"},{"name":"Idempotency","item":[],"id":"79503359-2a4b-4620-ad76-8faac1534877","description":"In the context of distributed systems and API integrations, network issues, timeouts, or client-side retries can cause duplicate requests to be sent unintentionally. Without safeguards, this can lead to duplicated data entries, double financial transactions, or inconsistent system states.
\nCPS-API V1 addresses this by supporting idempotency for all POST endpoints. This means that clients can safely retry a request without risk of reprocessing, as long as the same Idempotency-Key is used.
This mechanism enhances integration reliability and prevents unintended side effects during failure recovery, automation retries, or system restarts.
\nClients should include the Idempotency-Key header in all POST requests that mutate data:
POST /invoice/payment HTTP/1.1\nAuthorization: Bearer <access_token>\nIdempotency-Key: 550e8400-e29b-41d4-a716-446655440000\nContent-Type: application/json\n\nIf a duplicate request is made using the same key, the API will return the original response from the first submission rather than executing the operation again.
\nThis ensures that retrying a payment or credit note submission will not double-book the transaction.
\nEach Idempotency-Key is stored for 7 days. Within that window, if a request is repeated with the same key, the original response is returned.
After 7 days, the key expires, and the request will be treated as new.
\nIt is highly recommended that the Idempotency-Key follow the UUIDv4 format. This format ensures a high degree of uniqueness and helps prevent accidental collisions across distributed systems.
Clients are advised to generate a new UUIDv4 for each unique business operation and retain it during retry cycles to preserve idempotency behavior.
\n","auth":{"type":"noauth","isInherited":false},"_postman_id":"79503359-2a4b-4620-ad76-8faac1534877"},{"name":"Rate Limiting","item":[],"id":"5e3f8bdd-2ce0-4cb1-a3a8-7dae0d6672ed","description":"To ensure fair usage and maintain consistent API performance across all clients, CPS-API V1 enforces rate limiting. Each OAuth 2.0 client ID is subject to:
\n100 requests per minute
\n10,000 requests per day
\nThese limits help protect system stability and prevent abuse, especially in high-throughput or automated environments.
\nWhen clients approach or exceed rate limits, the API responds with an HTTP 429 Too Many Requests status. To support automated backoff strategies, rate limit headers are included in the response:
X-RateLimit-Limit: 100\nX-RateLimit-Remaining: 0\nRetry-After: 60\n\nX-RateLimit-Limit – The maximum number of allowed requests in the current window
X-RateLimit-Remaining – The number of remaining allowed requests
Retry-After – Number of seconds to wait before retrying
X-RateLimit-Reset – Unix timestamp (seconds since epoch, UTC) at which the rate limit will be reset
\nClients should implement throttling logic in their integration layer to avoid hitting these limits. Recommendations include:
\nMonitor the X-RateLimit-Remaining header and dynamically reduce request frequency as the threshold nears.
Use exponential backoff and retry after the duration specified in Retry-After.
Distribute requests over time, particularly during automated sync jobs or batch processing.
\nRespecting rate limits not only ensures uninterrupted access to CPS-API but also contributes to a stable, shared integration ecosystem for all clients.
\n","auth":{"type":"noauth","isInherited":false},"_postman_id":"5e3f8bdd-2ce0-4cb1-a3a8-7dae0d6672ed"},{"name":"API Capabilities","item":[],"id":"7516bf95-2415-4a63-a088-d9a3c13c24ae","description":"CPS-API V1 enables a set of well-defined, secure operations for managing debt collection cases and related financial events. Clients can:
\nRegister new debt collection cases, including customer and invoice data
\nSubmit follow-up transactions such as payments, credit notes, or invoice withdrawals
\nQuery case and invoice statuses
\nRetrieve financial transactions journalized by Intrum
\nPoll for asynchronous processing results using tracking IDs
\nNot allowed:
\nModifying an existing case once registered (only follow-up transactions like credit notes can affect financial position)
\nSubmitting incomplete or partial records (required fields must be fully provided)
\nInteracting directly with legal or escalated processes – these are managed internally by Intrum
\nSubmitting data in a synchronous expectation when endpoints are explicitly asynchronous (e.g., expecting immediate confirmation of case creation)
\nThe API is designed with the following principles in mind:
\nAsynchronous submission model: Several operations are processed in the background and confirmed via /tracking
Idempotency and fault tolerance: To support retries and system resilience
\nSecurity and isolation: Clients are scoped by credentials and access rights
\nMinimal impact for existing clients: New features and endpoints should not require major integration rewrites
\nCases cannot be deleted or fully reset once registered; lifecycle management must be done through updates and closures
\nThe API enforces strict schema validation and will reject loosely defined JSON payloads
\nThere is no built-in sandbox mode – testing must occur against the integration environment
\nThese boundaries are in place to ensure consistency, traceability, and compliance with operational and regulatory standards.
\n","auth":{"type":"noauth","isInherited":false},"_postman_id":"7516bf95-2415-4a63-a088-d9a3c13c24ae"},{"name":"Glossary","item":[],"id":"303d1ef8-3534-4888-a47b-3384cf6b0be7","description":"","auth":{"type":"noauth","isInherited":false},"_postman_id":"303d1ef8-3534-4888-a47b-3384cf6b0be7"},{"name":"Change Log","item":[],"id":"ba351366-2562-4f59-bce7-d8a882265202","description":"The API is designed with non-breaking change principles.
\nAll new endpoints or fields will be additive in nature.
\nNo optional fields will become required in future versions, as this would break existing integrations. Required fields may become optional if it enhances flexibility without affecting current clients.
\nDeprecation of endpoints, if necessary, will follow a communicated lifecycle including:
\nDeprecation announcement with timeline
\nContinued support for at least 6 months post-announcement
\nOptional feature flags or version negotiation mechanisms if adopted
\nFuture enhancements (e.g., customer-level endpoints, webhooks support, reporting APIs) will be released under version v1.x as long as they do not break existing integrations.
For any breaking changes, a major version bump to v2.0 will be applied with migration guidance.
URL: POST /portfolio/registration
Environment URLs:
\nIntegration (INT): https://collection.test-api-intrum.ch/restServices/v1/portfolio/registration
Production (PROD): https://collection.api-intrum.ch/restServices/v1/portfolio/registration
Authentication: OAuth 2.0 (Client Credentials Flow) – Authorization: Bearer
Idempotency: Supported via Idempotency-Key header (UUIDv4 recommended). Keys remain valid for 7 days.
Top-level attributes:
\nSupported claimType Values:
customer ObjectNote: Fields marked as \"Expected when customerType = X\" are not required, but strongly recommended for optimal processing. They should be included based on the customer classification.
\naddress Sub-Objectinvoices[] ArrayEach invoice includes:
\nattachments[] ArrayNote: The _attachments[]_ array is optional. However, when attachments are included, all listed fields become mandatory for each item.
invoiceAttributes[] ArrayNote: The _invoiceAttributes[]_ array is optional. However, when attachments are included, all listed fields become mandatory for each item.
attributeType GlossaryAsynchronous: Clients receive a trackingId and must poll /tracking to monitor processing status (e.g., REGISTERED, IN PROGRESS, COMPLETED, FAILED).
Retention: Tracking data is retained for 90 days.
\nEnsure uniqueness of invoiceNumber and itemId per client portfolio.
Always include Idempotency-Key on retries to prevent unintended duplicates.
Include all mandatory address fields and comply with ISO standards for codes.
\nThe POST /portfolio/registration endpoint is used to register new outstanding debts for collection. This is the primary method by which clients submit cases comprising customer, invoice, and claim-related data to Intrum’s Case Processing System (CPS). All submitted requests are processed asynchronously and return a trackingId for status monitoring via the /tracking endpoint.
URL: GET /portfolio/query
Environment URLs:
\nIntegration (INT): https://collection.test-api-intrum.ch/restServices/v1/portfolio/query
Production (PROD): https://collection.api-intrum.ch/restServices/v1/portfolio/query
Authentication: OAuth 2.0 (Client Credentials Flow)
\nThe caseNumber field is used as the sortBy attribute for pagination purposes in this endpoint.
invoices[] Array📘 Note: In the default response, the invoices array only contains a list of invoiceNumber values — it serves as a simple enumeration of all invoice references associated with the case. To access complete invoice-level financial and status data, each invoiceNumber can be used with the /invoices/query API.
productHistory[] Array (if addProductHistory=true)statusHistory[] Array (if addStatusHistory=true)Prefer customerReference and caseOpeningDateFrom for filtering new case registrations
Use limit and startingAfter for robust pagination
When hasMore is true, continue requesting pages until all results are retrieved
Unique identifier for a registered case
\n","type":"text/plain"},"key":"caseNumber","value":"External reference used by client to identify the customer
\n","type":"text/plain"},"key":"customerReference","value":"Minimum claimed amount for the case
\n","type":"text/plain"},"key":"minClaimed","value":"Maximum claimed amount for the case
\n","type":"text/plain"},"key":"maxClaimed","value":"Start date for case opening (YYYY-MM-DD)
\n","type":"text/plain"},"key":"caseOpeningDateFrom","value":"End date for case opening (YYYY-MM-DD)
\n","type":"text/plain"},"key":"caseOpeningDateTo","value":"If true, includes product assignment history in the response. false by default.
If true, includes status transitions over time in the response. false by default
Cursor for forward pagination based on last result ID, using caseNumber
\n","type":"text/plain"},"key":"startingAfter","value":"Cursor for backward pagination, using caseNumber
\n","type":"text/plain"},"key":"endingBefore","value":"Max number of records per page (default: 10, max: 100)
\n","type":"text/plain"},"key":"limit","value":"10"}],"variable":[]}},"response":[{"id":"0ddd8b07-948c-43fd-93ca-15c307e5251c","name":"successful request: default response","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"},{"description":"Added as a part of security scheme: oauth2","key":"Authorization","value":"