GuideReference

CaseControl API

Get started with the CaseControl API

High level overview of CaseControl

Main object types

The main object types in CaseControl are the following:

  • Cases

  • Relations

  • Relation Entities

In short, a case is a record of a debtor's debt to a creditor. A case can have multiple relations connected to it that each have a special relation type (Creditor, debtor, third party, lawyer, etc).

A relation can be connected to multiple relation entities, relation entities represent the organizations and natural persons within CaseControl. This means that the same natural person or organization can be a debtor in one relation, but also a creditor in another relation.

Authorization/authentication (OAuth2)

Introduction

OAuth (Open Authorization) is a secure and widely used authorization protocol that enables third-party applications to access protected resources on behalf of a resource owner. This chapter outlines the steps to integrate OAuth authorization with the CaseControl API.

Prerequisites

Before you begin, ensure that you have the following:

  • OAuth 2.0 Client: Use the client credentials (client ID and client secret) for secure access to protected resources.

  • API Access: Obtain the access credentials (client ID and client secret) from CaseControl.

Step-by-Step Guide

Step 1. Obtain Access Token

Send a POST request to the token endpoint to obtain an access token using client credentials:

POST https://api.casecontrol.app/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET

  • grant_type: Set to "client_credentials".

  • client_id and client_secret: Your OAuth client credentials.

Step 2. Access Protected Resources

Include the obtained access token in the header of your API requests:

GET {api_url_you_are_trying_to_access}
Authorization: Bearer ACCESS_TOKEN
Token Expiry

Access tokens obtained through the client credentials flow expire after 1 hour. Be prepared to refresh the token as needed.

Token Refresh (Optional)

If your access token expires, request a new one by repeating the token acquisition step.

Scopes

To limit access to certain resources, OAuth scopes are used. OAuth scopes can be requested for a specific access token by passing a scope parameter into the OAuth token request. The scopes that can be requested are set through the CaseControl client management interface.

The full list of scopes can be found under every endpoint under the scopes required by the endpoint itself.

Content tables

CaseControl uses content tables heavily throughout it's application and API. Content tables make it possible for users to add new properties to all sorts of lists throughout the CaseControl application. All of the content table data is available through the /locales endpoint. Some things to keep in mind are:

  • ID's are different between administrations, use the /locales endpoint to retrieve the correct ID for the localized data. Use the *_sys_id properties to get the correct programmatic value for a localized property.

  • The data from the /locales endpoint does not change very often and should be cached by your application to reduce server load

As an example on how content tables are used, see the below endpoint body for creating a natural person relation:

{
    "copy_of_relation_entity_id": null,
    "is_active": true,
    "natural_person": {
        "is_active": true,
        "status_id": 31, <-- Found in locales endpoint
        "gender_id": 19, <-- Found in locales endpoint
        "initials": null,
        "first_name": "Peter",
        "middle_name": null,
        "last_name": "van Spronsen",
        "birth_name": null,
        "place_of_birth": null,
        "date_of_birth": null,
        "date_deceased": null,
        "correspondence_title_id": 37, <-- Found in locales endpoint
        "correspondence_suffix_id": null, <-- Found in locales endpoint
        "correspondence_attention_of_id": 19, <-- Found in locales endpoint
        "correspondence_greeting_id": 19, <-- Found in locales endpoint
        "correspondence_salutation_id": 44, <-- Found in locales endpoint
        "language_id": 14, <-- Found in locales endpoint
    },
    "organization": null
}

To allow for a smooth transition between testing administrations and production administrations, please don't hardcode the administration-specific ID's in your code, but use the /locales endpoint to retrieve the correct ID for the localized data.

Pagination

Throughout the API there is a standard format for pagination. It looks like this:

{

    "meta": {
        "page": 1,
        "limit": 50,
        "total_count": 54,
        "current_page_count": 10
    },
    "data": [
        {}
    ]
}

  • meta: Contains information about the pagination status of the query

    • page: Indicates the current page

    • limit: Indicates the current limit

    • total_count: Indicates the total amount of items that conform to your query

    • current_page_count: Indicates the amount of items on the current page

  • data: Contains the data for your request

Versioning

The CaseControl API is versioned by url segment. When using a version of the CaseControl API (Current: v1) you can be sure that no breaking changes will be introduced. Here you can find a list of things that are considered breaking changes and things that are not

Breaking changes

  • Removing an endpoint

  • Removing a field from an endpoint

  • Renaming an endpoint

  • Renaming a field

  • Changing the type of a field

  • Changing the response format of an endpoint

Non-breaking changes

  • Adding a field to an endpoint

  • Adding an endpoint

  • Adding a non-required query parameter to an endpoint

  • Adding a new response format to an endpoint in combination with the existing response format

Error handling

The CaseControl API uses standard HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 400 range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with CaseControl's servers. The CaseControl API also follows the ProblemDetails specification for error responses. This means that the response body will contain a JSON object with the following properties:

  • type: A URI reference that identifies the problem type.

  • title: A short, human-readable summary of the problem.

  • status: The HTTP status code for the current request.

  • detail: A human-readable explanation specific to this occurrence of the problem.

  • instance: A URI reference that identifies the specific occurrence of the problem.

Support

If you have any questions or need help integrating the CaseControl API, please contact us at support@finchamps.com

© 2025 FinChamps