openapi: 3.2.0
info:
  title: Debitura Referral Partner Referral Partners API
  description: 'Welcome to the Debitura Referral API. This API allows you to set up new clients and track your revenue share with Debitura. You can also generate bearer tokens for use in the Customer API to create cases, check case status, and access all other endpoints. To get access to this API, please contact us at contact@debitura.com.


    📖 Full documentation, guides, and integration walkthroughs: https://docs.debitura.com/referral-partners'
  contact:
    name: Debitura Support
    url: https://www.debitura.com/integration
    email: contact@debitura.com
  version: v1
servers:
- url: https://referral-api.debitura.com
  description: Production
security:
- ApiKey: []
tags:
- name: ReferralPartners
  description: Referral Partners
paths:
  /me:
    get:
      tags:
      - ReferralPartners
      summary: Get authenticated partner information
      description: '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.'
      responses:
        '200':
          description: Partner information retrieved successfully
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.ReferralPartners.ReferralPartnerResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.ReferralPartners.ReferralPartnerResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.ReferralPartners.ReferralPartnerResponse'
        '404':
          description: Referral partner not found (invalid configuration)
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
components:
  schemas:
    Debitura.Domain.Model.ReferralPartners.Enums.InvoicingTriggerMode:
      enum:
      - PayWhenPaid
      - ConfirmedPipeline
      type: string
      description: "Controls what condition triggers a referral partner's payout to become \"ready to invoice\"\nDebitura for their referral fee. Per-partner override; see Debitura.Domain.Model.ReferralPartners.ReferralPartner.InvoicingTriggerMode.\n            \nThis enum is also returned directly on the ReferralPartnerApi `GET /me` response\n(`ReferralPartnerResponse.InvoicingTriggerMode`). Wire format is locked to named\nPascalCase string values (\"PayWhenPaid\", \"ConfirmedPipeline\") via Newtonsoft.Json\nStringEnumConverter — that host uses Newtonsoft (AddNewtonsoftJson in Program.cs), so a\nSystem.Text.Json JsonStringEnumConverter attribute alone would be silently ignored; both\nare declared so STJ-based consumers (and our own tests) can also deserialize the string form."
    Debitura.Web.ReferralPartnerApi.Models.ReferralPartners.ReferralPartnerResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the referral partner.
          format: uuid
        companyName:
          type:
          - string
          - 'null'
          description: Company name of the referral partner.
        shortName:
          type:
          - string
          - 'null'
          description: Short name of the referral partner.
        contactEmail:
          type:
          - string
          - 'null'
          description: Contact email for the referral partner.
        externalSystemId:
          type:
          - string
          - 'null'
          description: External system identifier for the partner.
        referralFeePercentage:
          type: number
          description: Percentage of Debitura's earnings that will be paid as referral fee.
          format: double
        isActive:
          type: boolean
          description: Whether the partner is currently active.
        isPublicDemo:
          type: boolean
          description: When true, this partner is used for public onboarding demos and may have demo-specific behaviour.
        logoUrl:
          type:
          - string
          - 'null'
          description: URL to the referral partner's logo image.
        backgroundColorCode:
          type:
          - string
          - 'null'
          description: Background color code for custom styling (e.g., "#FFFFFF").
        fontColor:
          type:
          - string
          - 'null'
          description: Font color code for custom styling (e.g., "#000000").
        fontFamily:
          type:
          - string
          - 'null'
          description: Font family for custom styling (e.g., "Arial, sans-serif").
        invoicingTriggerMode:
          $ref: '#/components/schemas/Debitura.Domain.Model.ReferralPartners.Enums.InvoicingTriggerMode'
      additionalProperties: false
      description: Response containing referral partner information including styling configuration.
    Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto:
      type: object
      properties:
        error:
          type:
          - string
          - 'null'
          description: Short human-readable error label (legacy field — preserved for backward compatibility).
        message:
          type:
          - string
          - 'null'
          description: Human-readable error description (legacy field — preserved for backward compatibility).
        businessErrors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.BusinessErrorApiDTO'
          description: Canonical structured error array. Consumers should migrate to reading this field.
      additionalProperties: false
      description: "Generic structured error response for API endpoints.\n            \nDual-write design: existing fields (Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto.Error / Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto.Message etc.)\nare preserved for backward compatibility alongside the canonical\nDebitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto.BusinessErrors array, allowing consumers to migrate at their own pace."
    Debitura.Web.ExternalApi.Contracts.V1.Cases.BusinessErrorApiDTO:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
        message:
          type:
          - string
          - 'null'
          description: A human-readable description of the error.
        solutionUrl:
          type:
          - string
          - 'null'
          description: "A URL where the user can resolve this <i>specific</i> error (e.g., sign a contract).\n            \n\nPartners who want a <b>single URL</b> that walks the user through every pending\nsigning in one chain — instead of forwarding one URL per\n`BusinessErrorApiDTO` — should use\nDebitura.Web.ExternalApi.Contracts.V1.Cases.BusinessErrorResponseApiDTO.SigningHandoff's `CombinedSigningUrl`.\nThe two are complementary: `SolutionUrl` is granular per-error;\n`CombinedSigningUrl` is the chain-walking alternative for signing-related errors."
      additionalProperties: false
      description: Represents a business error in the API response.
  securitySchemes:
    ApiKey:
      type: apiKey
      description: Referral Partner API Key (use XApiKey header)
      name: XApiKey
      in: header
externalDocs:
  description: Debitura developer documentation
  url: https://docs.debitura.com