POSTlive

Authorize one agreement-derived filing-fee referral

Requires fee_referrals:authorize on an explicitly provisioned platform_orchestrator. The server selects the active commercial account and immutable agreement version. The caller supplies referral identity and intended parties but cannot select a price, payer, billing cadence, account, or agreement. Authorization alone does not open a case.

/api/v2/fee-referralsauthorizePartnerFeeReferralV2

Authentication and authority

Send one of the allowed bearer credential roles. Alternatives are OR; credentials named within one alternative are AND.

platformOrchestratorBearer

Credential bound to the platform_orchestrator role.

Parameters

NameLocationRequirementSchema
Idempotency-KeyheaderRequired{"type":"string","minLength":8,"maxLength":200}

Request body

Required request body.

application/json

{
  "$ref": "#/components/schemas/PartnerFeeReferralInput",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "externalCaseId",
    "externalReferralId",
    "intendedParties",
    "feeType"
  ],
  "properties": {
    "externalCaseId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "externalReferralId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Partner-unique referral identity that does not depend on a payment transaction."
    },
    "externalTransactionId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Optional marketplace transaction provenance."
    },
    "intendedParties": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "claimantExternalId",
        "respondentExternalId"
      ],
      "properties": {
        "claimantExternalId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "respondentExternalId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        }
      }
    },
    "feeType": {
      "type": "string",
      "const": "filing"
    }
  }
}

Responses

200

An identical partner fee referral already exists.

application/json

{
  "$ref": "#/components/schemas/PartnerFeeReferralEnvelope",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "requestId"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/PartnerFeeReferral",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schemaVersion",
        "feeReferralAuthorizationId",
        "externalCaseId",
        "externalReferralId",
        "feeType",
        "status",
        "expiresAt"
      ],
      "properties": {
        "schemaVersion": {
          "type": "string",
          "const": "partner-fee-referral-authorization-v1"
        },
        "feeReferralAuthorizationId": {
          "type": "string"
        },
        "externalCaseId": {
          "type": "string"
        },
        "externalReferralId": {
          "type": "string"
        },
        "externalTransactionId": {
          "type": "string"
        },
        "feeType": {
          "type": "string",
          "const": "filing"
        },
        "status": {
          "type": "string",
          "const": "accepted"
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "requestId": {
      "type": "string"
    }
  }
}
201

Partner fee referral accepted.

application/json

{
  "$ref": "#/components/schemas/PartnerFeeReferralEnvelope",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "requestId"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/PartnerFeeReferral",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schemaVersion",
        "feeReferralAuthorizationId",
        "externalCaseId",
        "externalReferralId",
        "feeType",
        "status",
        "expiresAt"
      ],
      "properties": {
        "schemaVersion": {
          "type": "string",
          "const": "partner-fee-referral-authorization-v1"
        },
        "feeReferralAuthorizationId": {
          "type": "string"
        },
        "externalCaseId": {
          "type": "string"
        },
        "externalReferralId": {
          "type": "string"
        },
        "externalTransactionId": {
          "type": "string"
        },
        "feeType": {
          "type": "string",
          "const": "filing"
        },
        "status": {
          "type": "string",
          "const": "accepted"
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "requestId": {
      "type": "string"
    }
  }
}
default

RFC 9457 style problem response.

application/problem+json

{
  "$ref": "#/components/schemas/Problem",
  "type": "object",
  "required": [
    "type",
    "title",
    "status",
    "code",
    "detail",
    "requestId"
  ],
  "properties": {
    "type": {
      "type": "string",
      "format": "uri"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer"
    },
    "code": {
      "type": "string"
    },
    "detail": {
      "type": "string"
    },
    "requestId": {
      "type": "string"
    }
  }
}

Example response

Successful response

{
  "data": {
    "schemaVersion": "partner-fee-referral-authorization-v1",
    "feeReferralAuthorizationId": "feeReferralAuthorizationId_test",
    "externalCaseId": "marketplace_case_123",
    "externalReferralId": "externalReferralId_test",
    "feeType": "filing",
    "status": "accepted",
    "expiresAt": "2026-08-09T12:00:00.000Z"
  },
  "requestId": "requestId_test"
}

Usage notes

  • Responses reflect the current authoritative resource state.
  • Send a unique Idempotency-Key. An exact retry returns the stored result; reusing the key with a different request fails.
  • The request is accepted only when its credential, authority, case state, and resource preconditions are satisfied.