{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-parties-schema.json",
  "title": "Interested parties identity information",
  "description": "This block identifies all interested parties involved in transaction.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-payments-openapi.yml#/components/schemas/Parties",
  "type": "object",
  "required": [
    "roles"
  ],
  "properties": {
    "paymentAuthorizationToken": {
      "type": "string",
      "description": "The Payment Authorization Token is used in the labels and international-labels API calls to authorize payment, NSA contract Rates, and label MID ranges.",
      "readOnly": true
    },
    "roles": {
      "type": "array",
      "description": "Each Role represents a participant in the transaction and must only be used once.  The `LABEL_OWNER` Role must be specified. The `PAYER` role must be specified, unless following the PC Postage flow.",
      "readOnly": false,
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/Role"
      }
    }
  },
  "additionalProperties": true,
  "$defs": {
    "CRID": {
      "title": "Customer Registration Identifier",
      "maxLength": 18,
      "minLength": 2,
      "type": "string",
      "description": "A Customer Registration Identification number (CRID) is a USPS-generated numeric code that uniquely identifies a business at a location."
    },
    "MID": {
      "title": "Mailer Identifier",
      "pattern": "^(\\d{6}|\\d{9})$",
      "type": "string",
      "description": "The Mailer Identifier (MID) is a field within the Intelligent Mail barcode that is used to identify mailers. MIDs are assigned by the USPS® to a Mail Owner, Mailing Agent or other service providers who request them."
    },
    "ManifestMID": {
      "title": "Mailer Identification code",
      "pattern": "^(\\d{6}|\\d{9})$",
      "type": "string",
      "description": "The unique mailer identifier designated for the manifest."
    },
    "PaymentAccount": {
      "title": "Payment Account",
      "type": "object",
      "properties": {
        "accountType": {
          "type": "string",
          "description": "The type of payment account.  METER pricing is only available to PC Postage providers.",
          "enum": [
            "EPS",
            "PERMIT",
            "METER",
            "OMAS"
          ]
        },
        "accountNumber": {
          "type": "string",
          "description": "The Enterprise Payment Account number or PC Postage meter number to use for payment. Required when `accountType` is `EPS` or `METER`."
        },
        "permitNumber": {
          "type": "string",
          "description": "The permit number or Federal Agency Number to use for payment. Required when `accountType` is `PERMIT` or `OMAS`."
        },
        "permitZIP": {
          "maxLength": 5,
          "type": "string",
          "description": "The ZIP Code™ associated to the permit number. Required when `accountType` is `PERMIT` or `OMAS`."
        },
        "nonProfitStatus": {
          "type": "boolean",
          "description": "This status is applicable only for permits and indicates whether the permit has been issued to a non-profit organization.",
          "readOnly": true
        },
        "sufficientFunds": {
          "type": "boolean",
          "description": "This attribute is relevant only when an amount parameter is provided, and it informs the API caller whether the payment account holds sufficient funds to process the payment.",
          "readOnly": true
        }
      },
      "additionalProperties": true,
      "description": "Payment account information."
    },
    "Role": {
      "title": "Transaction roles",
      "type": "object",
      "additionalProperties": true,
      "description": "Role each party plays in the transaction",
      "allOf": [
        {
          "type": "object",
          "properties": {
            "roleName": {
              "type": "string",
              "description": "* PAYER - Payer of the Postage\n\n* RATE_HOLDER - Owner of the Contracted Postage Rates\n\n* LABEL_OWNER - Party supplying Label MIDs used for generating tracking numbers printed on physical label\n\n* SHIPPER - Party entering package into the mailstream\n\n* PLATFORM - Platform used\n\n* RETURN_LABEL_PAYER - Payer of the Postage for the return label in a combined outbound/return request. Optional if outbound and return label payer are the same.\n\n* RETURN_LABEL_RATE_HOLDER - Owner of the Contracted Postage Rates for the return label in a combined outbound/return request. Optional if outbound and return label rate holder are the same.\n\n* RETURN_LABEL_OWNER - Party supplying Label MIDs used for generating tracking numbers printed on physical label for the return label in a combined outbound/return request. Optional if outbound and return label owner are the same.\n\n* MAIL_OWNER - This role is used to specify who owns the package contents. When using the MAIL_OWNER role, the CRID must be specified.  This does not populate the mail owner field in the D1 record of the Shipping Service File (SSF).  Please use the `packageDescription.mailerOwnerMID` field to populate the D1 field.\n\n* LABEL_PROVIDER - This role is used to specify the label provider for the transaction. When using the LABEL_PROVIDER role, the CRID, accountNumber, and accountType must be specified and the only supported accountType is 'EPS'. The accountNumber must be active in the Enterprise Payment System (EPS).\n",
              "enum": [
                "PAYER",
                "RATE_HOLDER",
                "LABEL_OWNER",
                "SHIPPER",
                "MAIL_OWNER",
                "PLATFORM",
                "RETURN_LABEL_PAYER",
                "RETURN_LABEL_RATE_HOLDER",
                "RETURN_LABEL_OWNER",
                "LABEL_PROVIDER"
              ]
            },
            "CRID": {
              "$ref": "#/$defs/CRID"
            },
            "MID": {
              "$ref": "#/$defs/MID"
            },
            "manifestMID": {
              "$ref": "#/$defs/ManifestMID"
            }
          },
          "additionalProperties": true
        },
        {
          "$ref": "#/$defs/PaymentAccount"
        }
      ]
    }
  }
}