ReferralRedemption

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/akahu/main/json-schema/akahu-referral-redemption-schema.json",
  "title": "ReferralRedemption",
  "description": "A redemption of a referral code into a new application owned by the authenticated organisation.",
  "x-generated": "2026-10-26",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/akahu-referrals-api-openapi.yml#/components/schemas/ReferralRedemption",
  "oneOf": [
    {
      "$ref": "#/$defs/ReferralRedemptionProcessing"
    },
    {
      "$ref": "#/$defs/ReferralRedemptionCompleted"
    },
    {
      "$ref": "#/$defs/ReferralRedemptionFailed"
    }
  ],
  "$defs": {
    "ReferralOrgDetails": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "logo": {
          "type": "string",
          "description": "A URL referencing the org's logo in PNG format."
        }
      },
      "required": [
        "name"
      ],
      "description": "Details for an organisation involved in a referral."
    },
    "ReferralRedemptionCompleted": {
      "type": "object",
      "properties": {
        "_id": {
          "type": "string",
          "pattern": "^referral_redemption_[a-z0-9]{24,27}$",
          "description": "The unique ID of the referral redemption."
        },
        "referrer": {
          "$ref": "#/$defs/ReferralOrgDetails"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "_application": {
          "type": "string",
          "pattern": "^application_[a-z0-9]{24,27}$",
          "description": "The ID of the new application created. Only present when `status` is `completed`."
        },
        "status": {
          "type": "string",
          "enum": [
            "completed"
          ]
        }
      },
      "required": [
        "_id",
        "referrer",
        "created_at",
        "updated_at",
        "_application",
        "status"
      ]
    },
    "ReferralRedemptionFailed": {
      "type": "object",
      "properties": {
        "_id": {
          "type": "string",
          "pattern": "^referral_redemption_[a-z0-9]{24,27}$",
          "description": "The unique ID of the referral redemption."
        },
        "referrer": {
          "$ref": "#/$defs/ReferralOrgDetails"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "status": {
          "type": "string",
          "enum": [
            "failed"
          ]
        },
        "failure_reason": {
          "$ref": "#/$defs/ReferralRedemptionFailureReason"
        }
      },
      "required": [
        "_id",
        "referrer",
        "created_at",
        "updated_at",
        "status",
        "failure_reason"
      ]
    },
    "ReferralRedemptionFailureReason": {
      "type": "object",
      "properties": {
        "code": {
          "$ref": "#/$defs/ReferralRedemptionFailureReasonCode"
        },
        "message": {
          "type": "string",
          "default": "Sorry, something went wrong while redeeming this referral. Please try again later."
        }
      },
      "required": [
        "code"
      ],
      "description": "If a referral redemption has failed, this field provides additional information about what went wrong."
    },
    "ReferralRedemptionFailureReasonCode": {
      "type": "string",
      "enum": [
        "document_unavailable",
        "internal_error"
      ],
      "description": "The reason for a referral redemption's failure:\n\n - `document_unavailable` One or more referral snapshot artifacts are no longer available.\n\n - `internal_error` An unhandled internal error prevented the redemption from completing."
    },
    "ReferralRedemptionProcessing": {
      "type": "object",
      "properties": {
        "_id": {
          "type": "string",
          "pattern": "^referral_redemption_[a-z0-9]{24,27}$",
          "description": "The unique ID of the referral redemption."
        },
        "referrer": {
          "$ref": "#/$defs/ReferralOrgDetails"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "status": {
          "type": "string",
          "enum": [
            "processing"
          ]
        }
      },
      "required": [
        "_id",
        "referrer",
        "created_at",
        "updated_at",
        "status"
      ]
    }
  }
}