Skip to main content

Client Onboarding

Create and link clients (creditors) to your referral partner account.

Overview​

Before submitting cases on behalf of a client, you must create or link them in Debitura. This establishes the relationship between your platform, the client, and Debitura's collection network.

The flow:

  1. Call POST /clients with your externalTenantId
  2. Handle the response (201, 202, or 409)
  3. If onboarding is required, present the onboarding URL to your client
  4. Once onboarding is complete, mint a bearer token and submit cases
POST https://referral-api.debitura.com/clients
XApiKey: YOUR_API_KEY
Content-Type: application/json

{
  "externalTenantId": "your-unique-client-id",
  "company": {
    "name": "Acme Corp",
    "registrationNumber": "12345678",
    "countryAlpha2": "GB",
    "address": "123 Business Street",
    "city": "London",
    "postalCode": "EC1A 1BB"
  },
  "users": [
    {
      "email": "admin@acme.com",
      "firstName": "Jane",
      "lastName": "Smith",
      "isOnboardingUser": true
    }
  ]
}

Required Fields​

FieldDescription
externalTenantIdYour unique identifier for this client. Used for all future operations.
company.nameLegal company name
company.countryAlpha2ISO 3166-1 alpha-2 country code
usersAt least one user with isOnboardingUser: true

Response Handling​

201 Created — Client Ready​

The client is fully onboarded and ready. Proceed to mint a token and submit cases.

202 Accepted — Onboarding Required​

The client was created but must complete onboarding before cases can be submitted.

{
  "clientId": "abc123",
  "onboardingLinks": {
    "url": "https://referral.debitura.com/onboarding/companydetails/abc123"
  }
}

Important: Debitura does not send onboarding emails for referral flows. You must present the onboarding URL to your client (in-app, email, redirect).

409 Conflict — Client Already Exists​

Two scenarios:

Scenario A: Linking Required (ClientExistsNeedsLinking)​

The client exists in Debitura and must approve linking to your platform.

{
  "conflictResponse": {
    "type": "ClientExistsNeedsLinking",
    "onboardingLinks": {
      "url": "https://app.debitura.com/referralpartner/approve?token=xyz789"
    }
  }
}

Present the approval URL to the client. The link request expires after 7 days. After approval, they become a non-attributed client.

Scenario B: Already Linked (AlreadyLinkedToAnotherPartner)​

The client is already linked to a different referral partner. Contact Debitura support to resolve.

Scenario C: Different Tenant ID (AlreadyLinkedDifferentTenant)​

The client is already linked to your platform but with a different externalTenantId. You cannot link the same client with multiple tenant IDs.

Adding a Return URL​

Append a return URL to redirect clients back to your platform after onboarding:

https://referral.debitura.com/onboarding/companydetails/abc123?returnUrl=https://yourapp.com/onboarding-complete
URL Encoding

If your return URL contains query parameters, URL-encode it first:

const returnUrl = encodeURIComponent('https://yourapp.com/done?clientId=123');
const onboardingUrl = `${baseUrl}?returnUrl=${returnUrl}`;

See White-Label UI for customization options.

Including Cases​

You can include cases in the POST /clients request. Cases are validated and created alongside the client.

Client vs Debtor

The client object (your customer) has minimal required fields. The debtor object in each case has strict validation—see debtor requirements.

After Onboarding​

Once onboarding is complete:

  1. Mint a bearer token — See Authentication
  2. Submit cases — See Create a Case (uses the Customer API)
  3. Track progress — See Webhooks for real-time updates

Handling Abandoned Onboarding​

If a user starts onboarding but doesn't complete it (closes browser, etc.):

  1. Call POST /clients again with the same externalTenantId
  2. You'll receive 202 Accepted with a fresh onboarding URL
  3. Redirect the user to continue where they left off

The API is idempotent—repeated calls return the existing client, not an error.

202 on retry, not 409

If you created the client (got 202), retrying returns 202 again. You only get 409 if the client existed in Debitura before your first call.

See Client Lifecycle for the complete decision tree.

Error Handling​

ErrorCauseSolution
400 Bad RequestInvalid or missing fieldsCheck required fields and data formats
401 UnauthorizedInvalid API keyVerify your XApiKey header
409 ClientExistsNeedsLinkingClient exists in DebituraPresent approval URL to client (expires in 7 days)
409 AlreadyLinkedToAnotherPartnerClient linked to different partnerContact Debitura support
409 AlreadyLinkedDifferentTenantClient linked with different tenant IDUse the existing externalTenantId for this client

See Error Handling for the full error response format.