Skip to main content
Referral Partner API

Collection requests

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

GET /collection-requests

GET/collection-requests

Query parameters

  • externalTenantIdstring
  • creditorReferencestring

Returns

200 OK

  • iduuid
  • statusenum
    One ofawaiting_onboardingawaiting_approvalawaiting_signatureawaiting_kycneeds_fixingsubmittedrejectedexpiredprocessing
  • solutionUrlstringnullable
  • solutionTypeenumnullable

    Next action: onboarding, approval, sdca (initial/fallback SDCA), sdca_update, power_of_attorney, jurisdiction_pricing_appendix, kyc, fix or case. Null when no action is available. Status remains awaiting_signature for agreement work. The legacy signature value can appear only in an immutable keyed replay snapshot.

    One ofonboardingapprovalsdcasdca_updatepower_of_attorneyjurisdiction_pricing_appendixkycfixcasesignature
  • externalTenantIdstringnullable
  • clientobject
  • invoicesarray of objectsnullable
  • createdAtdatetime
  • updatedAtdatetime
GET/collection-requests
curl https://referral-api.debitura.com/collection-requests \
  -H "XApiKey: $DEBITURA_API_KEY"
Response
{
  "id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "status": "awaiting_onboarding",
  "solutionUrl": "https://app.debitura.com/…",
  "solutionType": "onboarding",
  "externalTenantId": "string",
  "client": {
    "debituraClientId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
    "isNew": true,
    "isAttributedClient": true
  },
  "invoices": [
    {
      "creditorReference": "INV-2026-0042",
      "status": "waiting",
      "caseId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
      "draftId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
      "caseStatus": "string",
      "reason": null,
      "issues": [
        {
          "field": {},
          "type": {},
          "message": {}
        }
      ]
    }
  ],
  "createdAt": "2026-10-01T14:05:00Z",
  "updatedAt": "2026-10-01T14:05:00Z"
}

Submit one invoice for collection

POST/collection-requests

Available only when Starter Integration is enabled. Send exactly one invoice in the invoices array. Return navigation uses the referral partner configuration; no per-request returnUrl is supported. Client details are used only on creation; existing clients approve a new connection. solutionUrl points to the first outstanding action: onboarding, approval, signature, KYC, fixing drafts, then the case. Resubmitting a client invoice reference returns its existing case within the same data classification.

Headers

  • Idempotency-Keystring
    Max 200 characters

Request body

  • externalTenantIdstringnullable
  • clientobject
  • userobject
  • invoicesarray of objectsnullable

Returns

201 Created

  • iduuid
  • statusenum
    One ofawaiting_onboardingawaiting_approvalawaiting_signatureawaiting_kycneeds_fixingsubmittedrejectedexpiredprocessing
  • solutionUrlstringnullable
  • solutionTypeenumnullable

    Next action: onboarding, approval, sdca (initial/fallback SDCA), sdca_update, power_of_attorney, jurisdiction_pricing_appendix, kyc, fix or case. Null when no action is available. Status remains awaiting_signature for agreement work. The legacy signature value can appear only in an immutable keyed replay snapshot.

    One ofonboardingapprovalsdcasdca_updatepower_of_attorneyjurisdiction_pricing_appendixkycfixcasesignature
  • externalTenantIdstringnullable
  • clientobject
  • invoicesarray of objectsnullable
  • createdAtdatetime
  • updatedAtdatetime

Errors

422Unprocessable Content

Every error uses the same body shape. See Error handling.

POST/collection-requests
curl -X POST https://referral-api.debitura.com/collection-requests \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "status": "awaiting_onboarding",
  "solutionUrl": "https://app.debitura.com/…",
  "solutionType": "onboarding",
  "externalTenantId": "string",
  "client": {
    "debituraClientId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
    "isNew": true,
    "isAttributedClient": true
  },
  "invoices": [
    {
      "creditorReference": "INV-2026-0042",
      "status": "waiting",
      "caseId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
      "draftId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
      "caseStatus": "string",
      "reason": null,
      "issues": [
        {
          "field": {},
          "type": {},
          "message": {}
        }
      ]
    }
  ],
  "createdAt": "2026-10-01T14:05:00Z",
  "updatedAt": "2026-10-01T14:05:00Z"
}

GET /collection-requests/{id}

GET/collection-requests/{id}

Path parameters

  • iduuidRequired

Returns

200 OK

  • iduuid
  • statusenum
    One ofawaiting_onboardingawaiting_approvalawaiting_signatureawaiting_kycneeds_fixingsubmittedrejectedexpiredprocessing
  • solutionUrlstringnullable
  • solutionTypeenumnullable

    Next action: onboarding, approval, sdca (initial/fallback SDCA), sdca_update, power_of_attorney, jurisdiction_pricing_appendix, kyc, fix or case. Null when no action is available. Status remains awaiting_signature for agreement work. The legacy signature value can appear only in an immutable keyed replay snapshot.

    One ofonboardingapprovalsdcasdca_updatepower_of_attorneyjurisdiction_pricing_appendixkycfixcasesignature
  • externalTenantIdstringnullable
  • clientobject
  • invoicesarray of objectsnullable
  • createdAtdatetime
  • updatedAtdatetime
GET/collection-requests/{id}
curl https://referral-api.debitura.com/collection-requests/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31 \
  -H "XApiKey: $DEBITURA_API_KEY"
Response
{
  "id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "status": "awaiting_onboarding",
  "solutionUrl": "https://app.debitura.com/…",
  "solutionType": "onboarding",
  "externalTenantId": "string",
  "client": {
    "debituraClientId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
    "isNew": true,
    "isAttributedClient": true
  },
  "invoices": [
    {
      "creditorReference": "INV-2026-0042",
      "status": "waiting",
      "caseId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
      "draftId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
      "caseStatus": "string",
      "reason": null,
      "issues": [
        {
          "field": {},
          "type": {},
          "message": {}
        }
      ]
    }
  ],
  "createdAt": "2026-10-01T14:05:00Z",
  "updatedAt": "2026-10-01T14:05:00Z"
}