Create an IPM Calendar

Use this REST API to create an IPM calendar for the specified application.

These standalone calendar APIs use native persistence. Creating a calendar does not associate forms or generate Insights.

Discover calendars using GET /HyperionPlanning/rest/v3/applications/{application}/objects with q={"objectType":"IPM Calendar"}. There is no separate calendar-list endpoint. Calendar GET requires a UUID; Insights generation looks up calendars by name.

After an uncertain POST response, check the objects API before retrying the create request.

Required Roles

Service Administrator or IPM - Manage. Native calendar access policy applies; the role check does not impose creator-only ownership.

REST Resource

POST /HyperionPlanning/rest/v3/applications/{application}/ipm/calendars

Authentication

Use HTTP Basic authentication. The specification declares basicAuth with the HTTP basic scheme.

Request

Supported Media Types: application/json

A JSON request body is required. Supply Content-Type: application/json.

Table 3-526 Path Parameters

Name Description Type Required Default
application Name of the application. Path Yes None

Table 3-527 Payload Parameters

Name Description Type Required Default
name Native calendar name. Exact same-parent names are protected by the database unique index. Detected case-insensitive conflicts return 409; concurrent case-only creates are not guaranteed to be rejected. Length: 1 to 80 characters. String Yes None
description Calendar description, up to 2000 characters. An empty string clears it; explicit null is rejected. String No Not specified
planTypes Cube names covered by the calendar. Supply an array containing at least one string. Array of strings Yes None
timeMemberSelection Member-selection expression defining the time axis, such as Year and Period members. String No Native calendar mapping
historicalStartMemberSelection Historical start coordinate, such as FY23->Jan. Mutually exclusive with historicalPeriods. String Conditional; select one historical boundary/count None
currentPeriodMemberSelection Current period coordinate and first prediction period. Historical periods precede it. Supply a member-selection expression, such as FY26->Jan, rather than an ISO date. String Yes None
predictionEndMemberSelection Inclusive prediction end coordinate, such as FY26->Jun. Mutually exclusive with futurePeriods. String Conditional; select one future boundary/count None
historicalPeriods Historical period count, at least 1. Effective historical periods must be at least twice the effective future periods. Integer Conditional; select one historical boundary/count None
futurePeriods Prediction period count, at least 1. Requires historicalPeriods; cannot be combined with historicalStartMemberSelection. Integer Conditional; select one future boundary/count None

The input must be a nonempty JSON object. Unknown fields, duplicate fields, and null-valued fields are not accepted. Native validation checks cube names, calendar mappings and period ranges.

Table 3-528 Historical and Prediction Period Selection

Historical Input Future Input Rule
historicalPeriods futurePeriods Allowed when effective historicalPeriods is at least twice effective futurePeriods.
historicalPeriods predictionEndMemberSelection Allowed; the server validates the effective period counts.
historicalStartMemberSelection predictionEndMemberSelection Allowed; the server validates the effective period counts.
historicalStartMemberSelection futurePeriods Not allowed. A future count requires a historical count.

Supply exactly one of historicalStartMemberSelection and historicalPeriods, and exactly one of predictionEndMemberSelection and futurePeriods. Historical periods precede currentPeriodMemberSelection. The server validates historicalPeriods >= 2 * futurePeriods using effective periods; an invalid ratio returns 400. Omitted calendar mapping uses the native default.

Table 3-529 Create and Read Property Names

Create Request Calendar Response
planTypes planType
timeMemberSelection calendarMbrSel
historicalStartMemberSelection startMbrSel
currentPeriodMemberSelection currentMbrSel
predictionEndMemberSelection endMbrSel

Example URL

The following example creates an IPM calendar in the Vision application.

https://<BASE-URL>/HyperionPlanning/rest/v3/applications/Vision/ipm/calendars

Example Payload

The following illustrative request supplies 36 historical periods and six future periods, satisfying the historical-to-future period ratio. Member-selection strings are not ISO dates.

{
  "name": "Insights_FY26",
  "description": "Prediction reconciliation pilot",
  "planTypes": [
    "Plan1"
  ],
  "timeMemberSelection": "ILvl0Descendants(Year)->ILvl0Descendants(YearTotal)",
  "currentPeriodMemberSelection": "FY26->Jan",
  "historicalPeriods": 36,
  "futurePeriods": 6
}

Response

Supported Media Types: application/json

A successful request returns HTTP status 201 Created and the effective Calendar representation.

Table 3-530 Response Headers

Name Value Description
Location Canonical UUID item URI Retrieve the created calendar using GET on this URI.
Cache-Control no-store Responses must not be stored.

Calendar responses use Cache-Control: no-store and do not support conditional GET.

Table 3-531 HTTP Response Codes

HTTP Status Description
201 Created calendar.
400 Invalid request.
401 Authentication required, or the application is unavailable to this caller under the shared Planning status mapping.
403 Insufficient access.
409 Conflicting calendar name.
500 Server processing failure.

Table 3-532 Calendar Response Parameters

Name Description Type Required
id Server-assigned calendar UUID. Read-only. String (UUID) Yes
revision Modification timestamp; treat it as an opaque revision. Read-only. String No
name Native calendar name; 1 to 80 characters. String Yes
description Calendar description, up to 2000 characters. String No
planType Cube names covered by the calendar. This response property is singular planType, unlike planTypes in the create request. Array of strings No
calendarMbrSel Effective calendar member-selection expression. String No
startMbrSel Historical start coordinate. String No
currentMbrSel Prediction start coordinate. String No
endMbrSel Inclusive prediction end coordinate. String No
historicalPeriods Effective historical period count; minimum 1. Integer No
futurePeriods Effective prediction period count; minimum 1. Integer No
links At least one link. Both POST and GET responses include a canonical GET link to the calendar UUID item URI. Array of Link Yes

The effective representation can contain both boundary selections and period counts. Do not echo the complete response as a create request: read representations retain native property names, while create requests use descriptive member-selection names.

Table 3-533 Link Parameters

Name Description Type Required
href Absolute resource or page URI. String (URI) Yes
action HTTP method for the link target. String Yes
rel Link relation: self, canonical, next, or prev. Calendar responses include canonical. String Yes

Table 3-534 Error Response Parameters

Name Description Type Required
status HTTP failure status. Integer Yes
detail Safe localized explanation of the failure. String Yes
message Planning compatibility error message, when supplied. String No
localizedMessage Localized Planning compatibility message, when supplied. String No
type Problem type URI, when supplied. String No
title Problem title, when supplied. String No
instance Problem instance URI, when supplied. String No
o:errorCode Oracle error code, when supplied. String No
o:errorPath Invalid field path, when supplied. String No
o:errorDetails Optional Oracle error-detail objects. The Calendar endpoint represents this property as an array. Array of ErrorDetail No

Error responses follow the shared Planning exception representation. Only status and detail are required by this schema. Problem-detail type/title and Oracle extension fields are optional because the shared mapper does not guarantee them. Nested o:errorDetails is an array for this Calendar endpoint.

Table 3-535 ErrorDetail Parameters

Name Description Type
type Problem type URI, when supplied. String
title Short problem title, when supplied. String
detail Human-readable explanation of the invalid request, when supplied. String
o:errorCode Oracle error identifier, when supplied. String
o:errorPath Request field associated with the error, when supplied. String

All ErrorDetail properties are optional and appear only when supplied by the shared mapper.

Example of a Successful Response

The following example uses illustrative values that follow the Calendar schema. The canonical link identifies the UUID item URI.

HTTP/1.1 201 Created
Location: https://<BASE-URL>/HyperionPlanning/rest/v3/applications/Vision/ipm/calendars/00000000-0000-0000-0000-000000000001
Cache-Control: no-store
Content-Type: application/json
{
  "id": "00000000-0000-0000-0000-000000000001",
  "revision": "2026-10-06 10:00:00.0",
  "name": "Insights_FY26",
  "description": "Prediction reconciliation pilot",
  "planType": [
    "Plan1"
  ],
  "calendarMbrSel": "ILvl0Descendants(Year)->ILvl0Descendants(YearTotal)",
  "startMbrSel": "FY23->Jan",
  "currentMbrSel": "FY26->Jan",
  "endMbrSel": "FY26->Jun",
  "historicalPeriods": 36,
  "futurePeriods": 6,
  "links": [
    {
      "href": "https://<BASE-URL>/HyperionPlanning/rest/v3/applications/Vision/ipm/calendars/00000000-0000-0000-0000-000000000001",
      "action": "GET",
      "rel": "canonical"
    }
  ]
}

Example of an Error Response

The specification provides the following HTTP 400 example for an invalid historical-to-future period ratio.

HTTP/1.1 400 Bad Request
{
  "status": 400,
  "detail": "Historical period count must be at least twice the future period count."
}