Skip to main content
Collection Partner API

Managed clients

Base URL
https://collectionpartner-api.debitura.com
Authentication
API key in the XApiKey header

Get current authority wording and creation availability.

GET/managed-clients/capability

Returns

200 OK

  • managedPartnerCaseCreationEnabledboolean
  • authorityVersionstringnullable
  • authorityWordingstringnullable

Errors

401Unauthorized
500Internal Server Error

See Error handling.

GET/managed-clients/capability
curl https://collectionpartner-api.debitura.com/managed-clients/capability \
  -H "XApiKey: $DEBITURA_API_KEY"
Response
{
  "managedPartnerCaseCreationEnabled": true,
  "authorityVersion": "string",
  "authorityWording": "string"
}

List represented clients.

GET/managed-clients

Page starts at 1; PageSize defaults to 25 (maximum 100). Query searches company names. ExternalClientId is an exact, case-sensitive reference. Results are ordered by company name, then ID.

Query parameters

  • pageinteger
  • pageSizeinteger
  • querystring
  • externalClientIdstring

Returns

200 OK

  • clientsarray of objectsnullable

    Minimal identity information for finding a represented client.

  • pageobject

    Stable v1 pagination metadata shared by public list responses.

Errors

400Bad Request
401Unauthorized
404Not Found
500Internal Server Error

See Error handling.

GET/managed-clients
curl https://collectionpartner-api.debitura.com/managed-clients \
  -H "XApiKey: $DEBITURA_API_KEY"
Response
{
  "clients": [
    {
      "id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
      "companyName": "Muster GmbH",
      "countryAlpha2": "DE",
      "externalClientId": "string"
    }
  ],
  "page": {
    "totalResults": 42,
    "pageSize": 25,
    "currentPage": 1,
    "responseCount": 42,
    "totalPages": 1
  }
}

Create a represented client.

POST/managed-clients

Obtain authority wording and version from GET /managed-clients/capability. One Idempotency-Key (1–255 non-whitespace characters) is required. Identical normalized retries return the same ID. A changed payload returns 422 IdempotencyConflict. Duplicate external references return 422 ExternalClientIdConflict. Missing or outdated authority acceptance returns 422 AuthorityRequired. An operation in progress returns 409 OperationInProgress with Retry-After: 2. Unsupported properties are rejected. Malformed JSON or model-binding failures return framework ValidationProblemDetails.

Headers

  • Idempotency-KeystringRequired

    Exactly one key, 1–255 non-whitespace characters.

Request body

  • companyNamestringnullableRequired

    Required company name, at most 200 characters after trimming.

    Max 200 characters
  • addressstringnullableRequired

    Required street address, at most 500 characters after trimming.

    Max 500 characters
  • citystringnullableRequired

    Required city, at most 200 characters after trimming.

    Max 200 characters
  • countryAlpha2stringnullableRequired

    Required two-letter country code, for example GB. Case-insensitive.

    Max 2 characters
  • zipCodestringnullable

    Optional postal code, at most 50 characters after trimming.

    Max 50 characters
  • statestringnullable

    Optional company state or region, at most 200 characters after trimming.

    Max 200 characters
  • companyRegistrationNumberstringnullable

    Optional company registration number, at most 50 characters after trimming.

    Max 50 characters
  • vatNumberstringnullable

    Optional VAT number, at most 50 characters after trimming.

    Max 50 characters
  • externalClientIdstringnullable

    Optional case-sensitive reference unique to your partner account, at most 200 characters.

    Max 200 characters
  • authorityAcceptedbooleanRequired

    Must be true to confirm authority under the current wording.

  • authorityVersionstringnullableRequired

    Current authority version from GET /managed-clients/capability.

Returns

200 OK

  • iduuid

Errors

400Bad Request
401Unauthorized
404Not Found
409Conflict
422Unprocessable Content
500Internal Server Error

See Error handling.

POST/managed-clients
curl -X POST https://collectionpartner-api.debitura.com/managed-clients \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Muster GmbH",
    "address": "Friedrichstraße 68",
    "city": "Berlin",
    "countryAlpha2": "DE",
    "authorityAccepted": true,
    "authorityVersion": "string"
  }'
Response
{
  "id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31"
}

Retrieve a represented client's current company details.

GET/managed-clients/{clientId}

Unavailable and inaccessible clients both return NotFound. Historical address fields can be null.

Path parameters

  • clientIduuidRequired

Returns

200 OK

  • iduuid
  • companyNamestringnullable
  • addressstringnullable
  • citystringnullable
  • countryAlpha2stringnullable
  • zipCodestringnullable
  • statestringnullable
  • companyRegistrationNumberstringnullable
  • vatNumberstringnullable
  • externalClientIdstringnullable

Errors

401Unauthorized
404Not Found
500Internal Server Error

See Error handling.

GET/managed-clients/{clientId}
curl https://collectionpartner-api.debitura.com/managed-clients/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31 \
  -H "XApiKey: $DEBITURA_API_KEY"
Response
{
  "id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "companyName": "Muster GmbH",
  "address": "Friedrichstraße 68",
  "city": "Berlin",
  "countryAlpha2": "DE",
  "zipCode": "10115",
  "state": "string",
  "companyRegistrationNumber": "DE123456789",
  "vatNumber": "DE123456789",
  "externalClientId": "string"
}

Replace the address of an unused represented client.

PUT/managed-clients/{clientId}

Only address, city, zipCode and state may be supplied. Omitted optional fields are cleared. Legal identity and external reference are immutable. Requires both creation flags enabled and no case (including deleted/test/closed), user access or commercial relationship history. GET the client first and send its ETag as one strong If-Match value. Missing: 428 PreconditionRequired; invalid: 400 InvalidPrecondition; stale: 412 PreconditionFailed. In-use: 409 ClientInUse; historical identity-less client: 409 ClientNotEditable. Success is 204 with the current ETag.

Path parameters

  • clientIduuidRequired

Headers

  • If-MatchstringRequired

    The strong ETag returned by GET for this client.

Request body

  • addressstringnullableRequired

    Required street address, at most 500 characters after trimming.

    Max 500 characters
  • citystringnullableRequired

    Required city, at most 200 characters after trimming.

    Max 200 characters
  • zipCodestringnullable

    Postal code, at most 50 characters. Omitted or null clears the value.

    Max 50 characters
  • statestringnullable

    State or region, at most 200 characters. Omitted or null clears the value.

    Max 200 characters

Returns

204 No Content — no response body.

Errors

400Bad Request
401Unauthorized
404Not Found
409Conflict
412Precondition Failed
428Precondition Required
500Internal Server Error

See Error handling.

PUT/managed-clients/{clientId}
curl -X PUT https://collectionpartner-api.debitura.com/managed-clients/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31 \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "Friedrichstraße 68",
    "city": "Berlin"
  }'
Response

204 No Content. No response body.

Soft-delete an unused represented client.

DELETE/managed-clients/{clientId}

Uses the same ownership, history, feature and If-Match restrictions as PUT. Authority, external reference reservations and create receipts are retained. No related records are deleted. Subsequent reads, mutations and original create replay return 404; the external reference cannot be reused. Success is 204 with no body.

Path parameters

  • clientIduuidRequired

Headers

  • If-MatchstringRequired

    The strong ETag returned by GET for this client.

Returns

204 No Content — no response body.

Errors

400Bad Request
401Unauthorized
404Not Found
409Conflict
412Precondition Failed
428Precondition Required
500Internal Server Error

See Error handling.

DELETE/managed-clients/{clientId}
curl -X DELETE https://collectionpartner-api.debitura.com/managed-clients/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31 \
  -H "XApiKey: $DEBITURA_API_KEY"
Response

204 No Content. No response body.