Skip to main content

Workflow: Client Linking

A comprehensive guide to linking your customers to Debitura and managing client relationships through the Referral Partner API.

Overview​

Client linking establishes the connection between your SaaS platform and Debitura, enabling you to create cases on behalf of your customers. This workflow covers the complete client lifecycle.

Client Lifecycle​

Create → Active → [Optional: Update] → [Optional: Suspend] → [Optional: Reactivate]

Creating a Linked Client​

Basic Client Creation​

Link a client with minimal required information:

POST /v1/referral-partners/clients

Request:

{
  "external_id": "your_customer_id_123",
  "company_name": "Customer Company AB",
  "country": "SE",
  "email": "contact@customer.com",
  "onboarding_type": "api_only"
}

Response:

{
  "client_id": "cli_abc123",
  "external_id": "your_customer_id_123",
  "status": "active",
  "bearer_token": "tok_xyz789",
  "created_at": "2024-01-15T10:00:00Z"
}

Advanced Client Creation​

Include additional details for better client management:

{
  "external_id": "your_customer_id_123",
  "company_name": "Customer Company AB",
  "country": "SE",
  "email": "contact@customer.com",
  "phone": "+46701234567",
  "vat_number": "SE123456789001",
  "onboarding_type": "white_label",
  "metadata": {
    "plan": "enterprise",
    "account_manager": "john@yourplatform.com",
    "signup_date": "2024-01-10"
  }
}

Onboarding Types​

API-Only Onboarding​

Use when: You want immediate API access without customer interaction.

{
  "onboarding_type": "api_only"
}

Behavior:

  • Client is immediately active
  • Bearer token provided in response
  • No customer onboarding flow required
  • Suitable for backend integrations

White-Label Onboarding​

Use when: You want customers to complete a branded onboarding experience.

{
  "onboarding_type": "white_label"
}

Behavior:

  • Client created in pending_onboarding status
  • Onboarding URL provided
  • Customer completes branded flow
  • Bearer token issued after completion

Learn more in White-Label Onboarding.

Managing Clients​

Retrieve Client Details​

Get information about a linked client:

GET /v1/referral-partners/clients/{client_id}

Response:

{
  "client_id": "cli_abc123",
  "external_id": "your_customer_id_123",
  "company_name": "Customer Company AB",
  "status": "active",
  "country": "SE",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z",
  "cases_count": 42,
  "total_volume": {
    "value": 125000,
    "currency": "SEK"
  }
}

List All Clients​

Retrieve all your linked clients with pagination:

GET /v1/referral-partners/clients?limit=50&offset=0

Query Parameters:

ParameterTypeDescription
limitintegerNumber of results per page (max 100)
offsetintegerNumber of results to skip
statusstringFilter by status: active, pending_onboarding, suspended
external_idstringFilter by your external ID

Update Client Information​

Modify client details as needed:

PATCH /v1/referral-partners/clients/{client_id}

Request:

{
  "email": "new-contact@customer.com",
  "phone": "+46701234567",
  "metadata": {
    "plan": "premium"
  }
}

Bearer Token Management​

Understanding Bearer Tokens​

The bearer token allows you to act on behalf of a linked client:

  • Scope: Specific to one client
  • Lifetime: Does not expire (unless revoked)
  • Usage: Include in Authorization header when creating cases
  • Security: Store securely, treat like passwords

Using Bearer Tokens​

Create cases on behalf of the client:

curl https://api.debitura.com/v1/cases \
  -H "Authorization: Bearer tok_xyz789" \
  -H "Content-Type: application/json" \
  -d '{...}'

Rotating Bearer Tokens​

If a token is compromised, rotate it:

POST /v1/referral-partners/clients/{client_id}/rotate-token

Response:

{
  "bearer_token": "tok_new_token_456",
  "previous_token_expires_at": "2024-01-20T10:00:00Z"
}

The old token remains valid for 24 hours to allow graceful transition.

Client Status Management​

Suspend a Client​

Temporarily disable a client's ability to create new cases:

POST /v1/referral-partners/clients/{client_id}/suspend

Use cases:

  • Customer payment issues on your platform
  • Terms of service violations
  • Customer requested pause

Effect:

  • Existing cases continue processing
  • New case creation blocked
  • Bearer token returns 403 Forbidden

Reactivate a Client​

Resume case creation for a suspended client:

POST /v1/referral-partners/clients/{client_id}/reactivate

External ID Mapping​

The external_id field helps you map Debitura clients to your internal customer IDs:

{
  "external_id": "your_customer_id_123"
}

Best practices:

  • Use your immutable customer ID
  • Keep it unique per client
  • Use it to look up clients in your system
  • Include it in webhook payloads

Find Client by External ID​

GET /v1/referral-partners/clients?external_id=your_customer_id_123

Metadata and Custom Fields​

Store custom data with each client using the metadata field:

{
  "metadata": {
    "subscription_tier": "enterprise",
    "account_manager": "jane@yourplatform.com",
    "custom_field": "any_value",
    "signup_date": "2024-01-10"
  }
}

Limitations:

  • Maximum 50 keys per client
  • Keys must be strings, max 40 characters
  • Values must be strings, numbers, or booleans
  • Total metadata size max 16KB

Best Practices​

Client Creation​

  • Always provide external_id for easy reference
  • Use meaningful company names
  • Validate email addresses before submission
  • Choose appropriate onboarding type

Token Security​

  • Store bearer tokens encrypted
  • Never log tokens in plaintext
  • Rotate tokens if compromised
  • Use environment variables

Error Handling​

  • Handle 409 conflicts gracefully (see Conflict Handling)
  • Implement retry logic for transient failures
  • Log client creation events for audit

Monitoring​

  • Track client creation metrics
  • Monitor failed linking attempts
  • Set up alerts for unusual patterns

Common Patterns​

Pattern 1: Just-in-Time Linking​

Link clients only when they first create a case:

async function ensureClientLinked(customerId) {
  // Check if already linked
  let client = await getClientByExternalId(customerId);

  if (!client) {
    // Link on first use
    client = await createLinkedClient({
      external_id: customerId,
      // ... other fields
    });
  }

  return client.bearer_token;
}

Pattern 2: Bulk Client Linking​

Link multiple existing customers at once:

async function bulkLinkClients(customers) {
  const results = await Promise.allSettled(
    customers.map(customer => createLinkedClient({
      external_id: customer.id,
      company_name: customer.name,
      // ... other fields
    }))
  );

  // Handle successes and failures
  return results;
}

Error Handling​

400 Bad Request - Invalid client data

{
  "error": {
    "type": "validation_error",
    "message": "Invalid country code",
    "field": "country"
  }
}

409 Conflict - Client already exists See Handling 409 Conflicts

429 Too Many Requests - Rate limit exceeded

{
  "error": {
    "type": "rate_limit_error",
    "message": "Too many requests",
    "retry_after": 60
  }
}

Next Steps​