POSTlive

Authorize one case-specific filing sponsorship referral

Requires the sponsorships:authorize capability on an explicitly provisioned platform_orchestrator credential. The server derives the sponsor, active agreement, $5 filing assessment, and environment; callers cannot select price or commercial terms. Authorization alone does not docket a case or accrue an obligation.

/api/v2/sponsorship-referralsauthorizeCaseSponsorshipReferralV2

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/CaseSponsorshipReferralInput",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "externalCaseId",
    "externalTransactionId",
    "intendedParties",
    "feeType"
  ],
  "properties": {
    "externalCaseId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "externalTransactionId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "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 coverage authorization already exists.

application/json

{
  "$ref": "#/components/schemas/CaseSponsorshipReferralEnvelope",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "requestId"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/CaseSponsorshipReferral",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schemaVersion",
        "referralAuthorizationId",
        "externalCaseId",
        "externalTransactionId",
        "feeType",
        "status",
        "expiresAt"
      ],
      "properties": {
        "schemaVersion": {
          "type": "string",
          "const": "case-referral-authorization-v1"
        },
        "referralAuthorizationId": {
          "type": "string"
        },
        "externalCaseId": {
          "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

Case-specific referral accepted.

application/json

{
  "$ref": "#/components/schemas/CaseSponsorshipReferralEnvelope",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "requestId"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/CaseSponsorshipReferral",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schemaVersion",
        "referralAuthorizationId",
        "externalCaseId",
        "externalTransactionId",
        "feeType",
        "status",
        "expiresAt"
      ],
      "properties": {
        "schemaVersion": {
          "type": "string",
          "const": "case-referral-authorization-v1"
        },
        "referralAuthorizationId": {
          "type": "string"
        },
        "externalCaseId": {
          "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": "case-referral-authorization-v1",
    "referralAuthorizationId": "referralAuthorizationId_test",
    "externalCaseId": "marketplace_case_123",
    "externalTransactionId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "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.