Create Reservation

Restriction: This API endpoint is not supported in the Free Trial cloud.

Creates a new device reservation.

URL

Copy 
https://<YOUR_CLOUD>.app.perfectomobile.com/api/v1/device-reservation/reservations

Method

POST

For information on a previous version of this endpoint, see Create Reservation | Legacy.

Header parameters

Name

Description

Perfecto-Authorization

The Perfecto security token. For more information, see Generate a security token.

Request parameters

Name

Type

Default

Description

admin

boolean

false

Set to true to allow users with administrative credentials to create reservations for users in their group.

Users with administrative credentials can create reservations that are longer than the max time frame.

Restriction: This parameter is not available on a shared MCM.

Request body

Name Type Description

resourceIds*

array

A comma separated list of deviceId in an array.

For example: ["value_1", "value_2"]

startTime*

long

The reservation start time, measured in milliseconds, from midnight, January 1, 1970 UTC (standard UNIX time).**

Tip: Use -1 to indicate current time.

endTime*

long

The reservation end time, measured in milliseconds, from midnight, January 1, 1970 UTC (standard UNIX time).**

reservedTo 

string

The user the device is reserved to. 

description 

string

The reservation description (free text). 

* Mandatory parameter

** Use this Timestamp converter to create the required time stamp for the new startTime and endTime values.

Copy

Sample request body

{
    "resourceIds": ["1234"],
    "startTime": "-1",
    "reservedTo": "<<USER_ID>>"
    "endTime": "1675920000000",
    "description": "Test description create"
}

Success response

Code: 200 OK

The response contains the generated reservationIds and a system timestamp of when the reservation was registered.

Copy 
{
    "reservationIds": [
        "636"
    ],
    "info": {
        "creationTime": {
            "formatted": "2023-02-09T05:00:52Z",
            "millis": "1675918852598"
        },
        "items": "1",
        "modelVersion": "2.6.0.0",
        "productVersion": "master",
        "time": "2023-02-09T05:00:52Z"
    }
}

Error response

Copy
Error response format
[
    {
        "userMessage":"ERROR_MESSAGE",
        "developerMessage": "1-63dbebb1-4521fab52df9f41a578221c8"
    }
]

where:

  • userMessage is the error message to be shown.

  • developerMessage is a value that you can send to Perfecto Support to check errors if further investigation is required.

An error is returned in the following cases:

  • The reservation feature is disable for the tenant.

  • The reservation start time is not valid.

  • The reservation period is not valid (it must be greater than 0).

  • The reservation period is less than 15 minutes.

Sample error responses

Copy
A wrong securityToken is passed in the request (Unauthorized Request Code - 401)
[
    {
        "userMessage": "Unable to authenticate bearer token",
        "developerMessage": "Unable to authenticate bearer token"
    }
]
Copy
The reservation is disabled for the tenant (Forbidden Request Code - 403) 
[
    {
        "userMessage": "Reservation is disabled. Please contact support.",
        "developerMessage": "5f4fb4e9c44e424faf0280d40dbbc8f2"
    }
]
Copy
The reservation start time is not valid (Bad Request Code - 400)
[
    {
        "userMessage": "Reservation start time is not valid",
        "developerMessage": "53b800d2a18e42839a5fbf6c0c356504"
    }
]
Copy
The endTime is passed as 0 (Bad Request Code - 400)
[
    {
        "userMessage": "Reservation period must be greater than 0(zero).",
        "developerMessage": "c43bf0add8db40c08ac7a20ca2254c60"
    }
]
Copy
A mandatory property is missing (Bad Request Code - 400)
[
    {
        "userMessage": "Mandatory property 'Resource Ids' is missing",
        "developerMessage": "de7b1588bfc441a680df489b1e8909da"
    }
]
Copy
The reservation period is less than 15 minutes
[
    {
        "userMessage": "The minimum reservation period is 15 minutes",
        "developerMessage": "3fed6bb17a08412cb376a932498f69ea"
    }
]