Source: https://docs.debitura.com/api/referral-partner-api/referral-partners

# Referral partners — Referral Partner API

Base URL: `https://referral-api.debitura.com`

Authentication: `XApiKey` API key; see [authentication](https://docs.debitura.com/developer-concepts/authentication.md).

Generated from [OpenAPI](https://docs.debitura.com/openapi/referral-partner-api.json). Examples are schema illustrations, not observed responses. Complete schemas, including recursive types, are in OpenAPI.

<a id="get-authenticated-partner-information"></a>

## Get authenticated partner information

`GET /me`

Retrieves complete configuration and styling information for the authenticated referral partner.

Authentication
- Requires a valid API key in the XApiKey header
- The API key uniquely identifies the referral partner

Response Data
- Partner identification (ID, system name, display name)
- Branding configuration (logo URLs, colors, fonts)
- Revenue sharing percentage
- Partner status and settings

Use Cases
- Configure white-label branding for client onboarding pages
- Display partner-specific styling in integrations
- Verify partner configuration and settings
- Retrieve commission/fee percentage for revenue calculations

The styling properties returned can be used to customize the appearance of onboarding pages
and other partner-facing interfaces to match the referral partner's branding.

### Response 200

Partner information retrieved successfully

- `id` (uuid): Unique identifier for the referral partner.
- `companyName` (string, nullable): Company name of the referral partner.
- `shortName` (string, nullable): Short name of the referral partner.
- `contactEmail` (string, nullable): Contact email for the referral partner.
- `externalSystemId` (string, nullable): External system identifier for the partner.
- `referralFeePercentage` (number): Percentage of Debitura's earnings that will be paid as referral fee.
- `isActive` (boolean): Whether the partner is currently active.
- `isPublicDemo` (boolean): When true, this partner is used for public onboarding demos and may have demo-specific behaviour.
- `logoUrl` (string, nullable): URL to the referral partner's logo image.
- `backgroundColorCode` (string, nullable): Background color code for custom styling (e.g., "#FFFFFF").
- `fontColor` (string, nullable): Font color code for custom styling (e.g., "#000000").
- `fontFamily` (string, nullable): Font family for custom styling (e.g., "Arial, sans-serif").
- `invoicingTriggerMode` (enum, nullable): What condition triggers payouts to become ready to invoice Debitura for this partner.
Null means the platform default (pay-when-paid). Set by Debitura; read-only here.
  Values: `PayWhenPaid`, `ConfirmedPipeline`, `null`.
- `billingMode` (enum): 
  Values: `PartnerInvoice`, `SelfBilling`.

```json
{
  "id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "companyName": "Muster GmbH",
  "shortName": "Muster GmbH",
  "contactEmail": "finance@example.com",
  "externalSystemId": "string",
  "referralFeePercentage": 2500,
  "isActive": true,
  "isPublicDemo": true,
  "logoUrl": "https://app.debitura.com/…",
  "backgroundColorCode": "string",
  "fontColor": "string",
  "fontFamily": "string",
  "invoicingTriggerMode": "PayWhenPaid",
  "billingMode": "PartnerInvoice"
}
```

### Response 404

Referral partner not found (invalid configuration)

- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.

```json
{
  "error": null,
  "message": "Payment plan agreed with the debtor.",
  "businessErrors": [
    {
      "type": "string",
      "message": "Payment plan agreed with the debtor.",
      "solutionUrl": "https://app.debitura.com/…"
    }
  ]
}
```

### Response 500

Internal server error

- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.

```json
{
  "error": null,
  "message": "Payment plan agreed with the debtor.",
  "businessErrors": [
    {
      "type": "string",
      "message": "Payment plan agreed with the debtor.",
      "solutionUrl": "https://app.debitura.com/…"
    }
  ]
}
```