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."
}