Skip to content
PerfectGym Next Open API
/
API reference
/
Finance
/
Get debt collection cases

PerfectGym Next API (1.7.0)

  • Appointment, bookable appointment and slots operations
  • Redeem checkin vouchers
  • Class and slots operations
  • Cross studio operations
  • Get customers and contracts
  • Retrieve customer accounting details
  • Retrieve customer communication details
  • Get device information
  • Employee operations
  • Debt collection operations
  • Manage membership contracts
  • Membership operations
  • Payment operations
  • Get studio information
  • Get trial offers information
Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Demo tenant

https://open-api-demo.open-api.perfectgym.com/

Mock server

https://redocly.sportalliance.com/_mock/apis/perfectgym/openapi/openapi/

Appointments

Appointment, bookable appointment and slots operations

Operations

Checkin vouchers

Redeem checkin vouchers

Operations

Classes

Class and slots operations

Operations

Cross Studio

Cross studio operations

Operations

Customers

Get customers and contracts

Operations

Customers Account

Retrieve customer accounting details

Operations

Customers Communication

Retrieve customer communication details

Operations

Customers Self-service

Operations

Devices

Get device information

Operations

Employees

Employee operations

Operations

Finance

Debt collection operations

Operations

Get Configuration of Debt Collection

Request

Required Scopes: DEBT_COLLECTION_READ

Get Configuration of Debt Collection

Security
ApiKeyAuth
curl -i -X GET \
  https://open-api-demo.open-api.perfectgym.com/v1/debt-collection/configuration \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
clientobject(ClientDetails)

The client matches a studio or location. The complete element should identify the person or company with its details of address, taxId, contact data and bank account information. An address should be complete, but only fields mandatory for all countries are marked as such

debtCollectionTypestring

Type of debt collection

Default "TRUST"
Enum ValueDescription
TRUST

Claims are transferred, but still managed by the studio.

PURCHASE

Claims are transferred and bought by the debt collection agency.

Example: "TRUST"
derecognizeRemainingDebtsOnClosurestring

Debt handling on positive or negative closure of case

Enum ValueDescription
BY_PARTNER

Indicates that the partner decides in update if the debt is written off.

ALWAYS

Indicates that the debt is always written off.

Example: "BY_PARTNER"
derecognizeRemainingDebtsOnRejectionstring

Debt handling on rejection or reversal of case

Enum ValueDescription
BY_PARTNER

Indicates that the partner decides in update if the debt is written off.

ALWAYS

Indicates that the debt is always written off.

Example: "BY_PARTNER"
Response
application/json
{
  "client": {
    "name1": "GYMLAB Hamburg",
    "name2": "GMBH",
    "legalForm": "GmbH",
    "preTaxAttribute": false,
    "vatSerialNo": "DE 142156559",
    "postalCode": "1180",
    "city": "Vienna",
    "countryCode": "AT",
    "country": "Australia",
    "paymentDetails": { … },
    "contactDetails": [ … ],
    "addressLine1": "Burgring 22",
    "addressLine2": "1180 Vienna",
    "addressLine3": "Austria",
    "region": "Vienna",
    "addressData": { … }
  },
  "debtCollectionType": "TRUST",
  "derecognizeRemainingDebtsOnClosure": "BY_PARTNER",
  "derecognizeRemainingDebtsOnRejection": "BY_PARTNER"
}

Get Debtors

Request

Required Scopes: DEBT_COLLECTION_READ

Returns debtors for specified debtCollectionRunId in slices

Security
ApiKeyAuth
Path
debtCollectionRunIdinteger(int64)required

Unique ID of the debt collection run

Query
offsetstring

Offset from last request

Default "0"
sliceSizeinteger(int32)[ 1 .. 50 ]

Desired size of data chunk

Default 10
curl -i -X GET \
  'https://open-api-demo.open-api.perfectgym.com/v1/debt-collection/{debtCollectionRunId}/debtors?offset=0&sliceSize=10' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
resultArray of objects(Debtor)required

List of debtors

result[].​debtorIdstringrequired

Debtor unique id

Example: "2334545"
result[].​membershipNrstringrequired

Membership number of the debtor

Example: "1568462597"
result[].​countryCodestring

Country code of the debtor

Example: "AT"
result[].​countrystring

Country of the debtor

Example: "Austria"
result[].​identificationNumberstring

Identification number of the debtor

Example: "ATU143543"
result[].​paymentDetailsobject(PaymentDetails)

Describes the payment data.

result[].​contractDetailsArray of objects(ContractDetails)

Contract data of the debtor

result[].​birthdatestring(date)

Birth date of the debtor

Example: "1952-05-04"
result[].​firstNamestringrequired

First name of the debtor

Example: "Sven"
result[].​lastNamestringrequired

Last name of the debtor name

Example: "Hannawald"
result[].​secondLastNamestring

Second last name of the debtor name

Example: "Shmidt"
result[].​sexstringrequired

Sex of the debtor

Example: "MALE"
result[].​postalCodestring

Postal code of the debtor

Example: "1180"
result[].​citystringrequired

City of the debtor

Example: "Vienna"
result[].​liablePersonobject(LiablePersonDetails)

The LiablePerson is used for members not being responsible themself for payments. The complete element should identify the liable person with its details of address, contact data and bank account information. It includes also country specific elements.

result[].​contactDetailsArray of objects(ContactDetails)

Contact numbers of the debtor

result[].​collectionCasesArray of objects(CollectionCase)

Collection case of the debtor

result[].​addressLine1string

Address first line

Example: "Burgring 22"
result[].​addressLine2string

Address second line

Example: "1180 Vienna"
result[].​addressLine3string

Address third line

Example: "Austria"
result[].​regionstring

Region of the debtor

Example: "Vienna"
result[].​addressDataobject(AddressDetails)

Describes the address in detail, so every country has its own fields filled. Use addressLines for preformatted address.

result[].​blockobject(OpenApiV1Block)

Debtor is blocked for collection cases

hasNextbooleanrequired

True if there exists next data slice

Example: true
offsetstringrequired

Offset for next query

Example: "1234567890"
Response
application/json
{
  "result": [
    { … }
  ],
  "hasNext": true,
  "offset": "1234567890"
}

Get Transfer Details

Request

Required Scopes: DEBT_COLLECTION_READ

Get transfer details by specified debtCollectionRunId

Security
ApiKeyAuth
Path
debtCollectionRunIdinteger(int64)required

Unique ID of the debt collection run

curl -i -X GET \
  'https://open-api-demo.open-api.perfectgym.com/v1/debt-collection/{debtCollectionRunId}/details' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
collectionDatestring(date)

Date when debt collection run was created

Example: "1952-05-04"
debtCollectionTypestring

Type of debt collection

Default "TRUST"
Enum ValueDescription
TRUST

Claims are transferred, but still managed by the studio.

PURCHASE

Claims are transferred and bought by the debt collection agency.

Example: "TRUST"
clientobject(ClientDetails)

The client matches a studio or location. The complete element should identify the person or company with its details of address, taxId, contact data and bank account information. An address should be complete, but only fields mandatory for all countries are marked as such

statusstring

Status of a Transfer

Enum ValueDescription
COMPLETED

Processing is done and the Agency has confirmed the retrieval of the Transfer.

INTERNAL_PROCESSING

The transfer is currently processed by Magicline.

FAILED

At any of the previous stages an error occurred.

WAITING_FOR_CONFIRMATION

Processing is done, the Agency should have received a Webhook Notification and should confirm retrieval of the Transfer.

Example: "COMPLETED"
originstring

Origin of debt collection

Enum ValueDescription
INDIVIDUAL_HANDOVER

Indicates that the debt was handed over via an individual transfer in the member account.

AUTOMATIC_HANDOVER

Indicates that the debt was handed over automatically due to a MemberCash rejection.

CONTRACT_CANCELATION

Indicates that the debt was handed over alongside the manual cancellation of a contract.

DEBT_COLLECTION_RUN

Indicates that the debt was part of a regular or scheduled debt collection run.

Example: "DEBT_COLLECTION_RUN"
Response
application/json
{
  "collectionDate": "1952-05-04",
  "debtCollectionType": "TRUST",
  "client": {
    "name1": "GYMLAB Hamburg",
    "name2": "GMBH",
    "legalForm": "GmbH",
    "preTaxAttribute": false,
    "vatSerialNo": "DE 142156559",
    "postalCode": "1180",
    "city": "Vienna",
    "countryCode": "AT",
    "country": "Australia",
    "paymentDetails": { … },
    "contactDetails": [ … ],
    "addressLine1": "Burgring 22",
    "addressLine2": "1180 Vienna",
    "addressLine3": "Austria",
    "region": "Vienna",
    "addressData": { … }
  },
  "status": "COMPLETED",
  "origin": "DEBT_COLLECTION_RUN"
}

Update debt collection

Request

Required Scopes: DEBT_COLLECTION_WRITE

Security
ApiKeyAuth
Bodyapplication/jsonrequired

Debt collection update details

debtorsArray of objects(DebtorUpdate)required

List of debtors with their payments

debtors[].​debtorIdstringrequired

Debtor unique id

Example: "2334545"
debtors[].​agencyCollectionCasesArray of objects(AgencyCollectionCaseUpdate)required

List of debt collection cases

debtors[].​agencyCollectionCases[].​agencyCollectionCaseIdstringrequired

ID the agency has assigned to this case

Example: "agency-id-123"
debtors[].​agencyCollectionCases[].​publicCollectionCaseIdstring

Optional customer facing identifier for this case, if there is one that differs from agencyCollectionCaseId and is used in human correspondence.

Example: "case-john-wayne-1"
debtors[].​agencyCollectionCases[].​collectionCaseIdsArray of stringsrequired

List of collection case ids which we have created, aggregated for that collection case

Example: ["123e4567-e89b-42d3-a456-556642440000"]
debtors[].​agencyCollectionCases[].​closureobject(ClosureUpdate)

Must be set in case the case has been closed, omit this entirely if the case isn't closed.

debtors[].​agencyCollectionCases[].​debtsArray of objects(DebtUpdate)required

Debts which were transferred to the agency. At least all changed debts must be included, also unchanged debts can be included.

debtors[].​agencyCollectionCases[].​debts[].​debtIdstringrequired

Debt id from the Transfer, identifying a debt, in UUID format

Example: "123e4567-e89b-42d3-a456-556642440000"
debtors[].​agencyCollectionCases[].​debts[].​originalAmountnumberrequired

Transferred amount to debt collection agency. Cancelled amount + paid amount should not be higher than original amount.

Example: 100
debtors[].​agencyCollectionCases[].​debts[].​canceledAmountnumberrequired

Not accepted amount. If the case is closed and writeOffRemainingDebts is set, they will be written off and not opened again.

Example: 0
debtors[].​agencyCollectionCases[].​debts[].​paidAmountnumberrequired

Paid amount, the status should always contain the amount which was paid to the debt collection agency. If paidAmount is higher than original amount, the loose rest will still be booked to the debtor.

Example: 100
debtors[].​agencyCollectionCases[].​debts[].​currencystringrequired

ISO 4217 currency of the debt code

Example: "EUR"
debtors[].​agencyCollectionCases[].​debts[].​blockobject(OpenApiV1BlockDto)

Option to block the debt for future collection cases. If no block is sent an existing block will be removed.

debtors[].​blockobject(OpenApiV1BlockDto)

Option to block the debtor for future collection cases. If no block is sent an existing block will be removed.

requestIdstringrequired

Request unique UUID id

Example: "fc336b0b-409c-4c66-a26d-ab25b87dcb8f"
curl -i -X POST \
  https://open-api-demo.open-api.perfectgym.com/v1/debt-collection/update \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "debtors": [
      {
        "debtorId": "2334545",
        "agencyCollectionCases": [
          {
            "agencyCollectionCaseId": "agency-id-123",
            "publicCollectionCaseId": "case-john-wayne-1",
            "collectionCaseIds": [
              "123e4567-e89b-42d3-a456-556642440000"
            ],
            "closure": {
              "type": "POSITIVE",
              "options": [
                {}
              ],
              "date": "2022-09-20",
              "rejectionReason": "CLAIMS_ALREADY_IN_COURT",
              "closureReason": "Not successful due to mail not successfully delivered"
            },
            "debts": [
              {
                "debtId": "123e4567-e89b-42d3-a456-556642440000",
                "originalAmount": 100,
                "canceledAmount": 0,
                "paidAmount": 100,
                "currency": "EUR",
                "block": {}
              }
            ]
          }
        ],
        "block": {
          "limitType": "LIMITED",
          "endDate": "2022-09-20"
        }
      }
    ],
    "requestId": "fc336b0b-409c-4c66-a26d-ab25b87dcb8f"
  }'

Responses

OK

Response
No content

Confirm transfer retrieval

Request

Required Scopes: DEBT_COLLECTION_WRITE

After fetching all data (details and debtors) related to a transfer use this endpoint to confirm the retrieval. This will flag the related data in Magicline as retrieved by the Agency. This endpoint should only be called if the status of the transfer is WAITING_FOR_CONFIRMATION (see getTransferDetails)

Security
ApiKeyAuth
Path
debtCollectionRunIdinteger(int64)required

Unique ID of the debt collection run

curl -i -X POST \
  'https://open-api-demo.open-api.perfectgym.com/v1/debt-collection/{debtCollectionRunId}/confirmTransfer' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK, we received the confirmation. If the transfer was already confirmed (e.g. retransmission) also 200 is returned.

Response
No content

Get debt collection cases

Request

Required Scopes: DEBT_COLLECTION_READ

Returns the current state of debt collection cases specified by debtorId, collectionCaseId and agencyCollectionCaseId. Each parameter has maximum allowable 50 ids.

Security
ApiKeyAuth
Query
debtorIdArray of strings[ 0 .. 50 ] items

Unique ID of the debtor

collectionCaseIdArray of strings[ 0 .. 50 ] items

The case id provided by Magicline. This is returned from the 'Get Debtors' endpoint as 'collectionCaseId'

agencyCollectionCaseIdArray of strings[ 0 .. 50 ] items

The case ID used by the agency. This relates to the 'agencyCollectionCaseId' parameter used in the 'Update debt collection' endpoint.

caseAdjustmentRequestIdinteger(int64)

The request ID delivered by webhook entityId. It contains the latest changes to a case in the Magicline.

curl -i -X GET \
  'https://open-api-demo.open-api.perfectgym.com/v1/debt-collection/cases?debtorId=string&collectionCaseId=string&agencyCollectionCaseId=string&caseAdjustmentRequestId=0' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/jsonArray [
debtorIdstringrequired

Debtor unique id

Example: "2334545"
agencyCollectionCasesArray of objects(AgencyCollectionCaseUpdate)required

List of debt collection cases

agencyCollectionCases[].​agencyCollectionCaseIdstringrequired

ID the agency has assigned to this case

Example: "agency-id-123"
agencyCollectionCases[].​publicCollectionCaseIdstring

Optional customer facing identifier for this case, if there is one that differs from agencyCollectionCaseId and is used in human correspondence.

Example: "case-john-wayne-1"
agencyCollectionCases[].​collectionCaseIdsArray of stringsrequired

List of collection case ids which we have created, aggregated for that collection case

Example: ["123e4567-e89b-42d3-a456-556642440000"]
agencyCollectionCases[].​closureobject(ClosureUpdate)

Must be set in case the case has been closed, omit this entirely if the case isn't closed.

agencyCollectionCases[].​debtsArray of objects(DebtUpdate)required

Debts which were transferred to the agency. At least all changed debts must be included, also unchanged debts can be included.

agencyCollectionCases[].​debts[].​debtIdstringrequired

Debt id from the Transfer, identifying a debt, in UUID format

Example: "123e4567-e89b-42d3-a456-556642440000"
agencyCollectionCases[].​debts[].​originalAmountnumberrequired

Transferred amount to debt collection agency. Cancelled amount + paid amount should not be higher than original amount.

Example: 100
agencyCollectionCases[].​debts[].​canceledAmountnumberrequired

Not accepted amount. If the case is closed and writeOffRemainingDebts is set, they will be written off and not opened again.

Example: 0
agencyCollectionCases[].​debts[].​paidAmountnumberrequired

Paid amount, the status should always contain the amount which was paid to the debt collection agency. If paidAmount is higher than original amount, the loose rest will still be booked to the debtor.

Example: 100
agencyCollectionCases[].​debts[].​currencystringrequired

ISO 4217 currency of the debt code

Example: "EUR"
agencyCollectionCases[].​debts[].​blockobject(OpenApiV1BlockDto)

Option to block the debt for future collection cases. If no block is sent an existing block will be removed.

blockobject(OpenApiV1BlockDto)

Option to block the debtor for future collection cases. If no block is sent an existing block will be removed.

]
Response
application/json
[
  {
    "debtorId": "2334545",
    "agencyCollectionCases": [ … ],
    "block": { … }
  }
]

Get blocked debt collection debtors

Request

Required Scopes: DEBT_COLLECTION_READ

Security
ApiKeyAuth
Query
debtorIdArray of strings

Unique ID of the debtor

offsetstring

Offset from last request

Default "0"
sliceSizeinteger(int32)[ 1 .. 50 ]

Desired size of data chunk

Default 10
curl -i -X GET \
  'https://open-api-demo.open-api.perfectgym.com/v1/debt-collection/blocked/debtors?debtorId=string&offset=0&sliceSize=10' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
resultArray of objects(DebtorId)required

List of debtors

result[].​debtorIdstringrequired

Debtor unique id

Example: "2334545"
result[].​blockobject(OpenApiV1Block)

Debtor is blocked for collection cases

result[].​debtsArray of objects(Debt)

Debts of the debtor

hasNextbooleanrequired

True if there exists next data slice

Example: true
offsetstringrequired

Offset for next query

Example: "1234567890"
Response
application/json
{
  "result": [
    { … }
  ],
  "hasNext": true,
  "offset": "1234567890"
}

Get blocked debt collection debts

Request

Required Scopes: DEBT_COLLECTION_READ

Security
ApiKeyAuth
Query
debtIdArray of strings(uuid)

Unique ID of the debt

offsetstring

Offset from last request

Default "0"
sliceSizeinteger(int32)[ 1 .. 50 ]

Desired size of data chunk

Default 10
curl -i -X GET \
  'https://open-api-demo.open-api.perfectgym.com/v1/debt-collection/blocked/debts?debtId=497f6eca-6276-4993-bfeb-53cbbbba6f08&offset=0&sliceSize=10' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
resultArray of objects(DebtorId)required

List of debtors

result[].​debtorIdstringrequired

Debtor unique id

Example: "2334545"
result[].​blockobject(OpenApiV1Block)

Debtor is blocked for collection cases

result[].​debtsArray of objects(Debt)

Debts of the debtor

hasNextbooleanrequired

True if there exists next data slice

Example: true
offsetstringrequired

Offset for next query

Example: "1234567890"
Response
application/json
{
  "result": [
    { … }
  ],
  "hasNext": true,
  "offset": "1234567890"
}

Create tax advisor export

Request

Required Scopes: TAX_ADVISOR_EXPORT_WRITE

Returns the export id

Security
ApiKeyAuth
Bodyapplication/jsonrequired
fromDatestring(date)required

Bookings accounting date range start. Must be in past and equal or before the toDate. The maximum time range is 90 days.

Example: "2020-12-15"
toDatestring(date)required

Bookings accounting date range end. Must be in past and equal or after the fromDate. The maximum time range is 90 days.

Example: "2020-12-30"
exportFormatstringrequired

The export format of bookings

Enum ValueDescription
SINGLE

Contains all bookings as a single unit

AGGREGATED

Bookings are aggregated by account numbers

Example: "AGGREGATED"
exportFileFormatstringrequired

The file format of the export

Enum ValueDescription
XLSX

Microsoft Excel

CSV

Comma Separated Values

JSON

JavaScript Object Notation

Example: "JSON"
exportLocalestring

The locale of the export.

Enum ValueDescription
ENGLISH

English

GERMAN

German

Example: "ENGLISH"
curl -i -X POST \
  https://open-api-demo.open-api.perfectgym.com/v1/taxadvisor/exports/create \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "fromDate": "2020-12-15",
    "toDate": "2020-12-30",
    "exportFormat": "AGGREGATED",
    "exportFileFormat": "JSON",
    "exportLocale": "ENGLISH"
  }'

Responses

OK

Bodyapplication/json
exportIdinteger(int64)

Id of created export

Response
application/json
{
  "exportId": 0
}

Get tax advisor export by id

Request

Required Scopes: TAX_ADVISOR_EXPORT_READ

Returns export download data like the download URL

Security
ApiKeyAuth
Path
exportIdinteger(int64)required

The exportId received from createExport

curl -i -X GET \
  'https://open-api-demo.open-api.perfectgym.com/v1/taxadvisor/exports/{exportId}' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
fromDatestring(date)required

Bookings accounting date range start

Example: "2020-12-15"
toDatestring(date)required

Bookings accounting date range end

Example: "2020-12-30"
exportFileFormatstringrequired

The file format of the export

Enum ValueDescription
XLSX

Microsoft Excel

CSV

Comma Separated Values

JSON

JavaScript Object Notation

Example: "JSON"
exportFormatstringrequired

The export format of bookings

Enum ValueDescription
SINGLE

Contains all bookings as a single unit

AGGREGATED

Bookings are aggregated by account numbers

Example: "AGGREGATED"
exportLocalestring

The locale of the export.

Enum ValueDescription
ENGLISH

English

GERMAN

German

Example: "ENGLISH"
downloadUrlstringrequired

The download file URL of the export. It will expire after 15 minutes.

Response
application/json
{
  "fromDate": "2020-12-15",
  "toDate": "2020-12-30",
  "exportFileFormat": "JSON",
  "exportFormat": "AGGREGATED",
  "exportLocale": "ENGLISH",
  "downloadUrl": "string"
}

Membership Self-service

Manage membership contracts

Operations

Memberships

Membership operations

Operations

Payments

Payment operations

Operations

Studios

Get studio information

Operations

Trial Offers

Get trial offers information

Operations