Connect Device to Cradle

Restriction: To be able to run this API endpoint, you need to be a lab admin user.

Connects a device to any cradle or to a specific cradle when the cradle ID is included in the request. Using this endpoint involves the following steps:

  1. Sending a POST request to connect a device. This request returns a task ID.

  2. Sending a GET request to check the status of the connect device operation performed using the task ID.

    Try to hit the GET request every 10 seconds till you get the final status as COMPLETE or ERROR.

Step 1 | Submit a request to connect the device

Use the following HTTP POST command to generate a task ID.

Method API

POST
Copy 
https://<your_cloud>.app.perfectomobile.com/api/v1/device-management/devices/connect

Header parameters

Add the following header parameters to the request.

Name Description

Perfecto-Authorization

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

Request parameters

Name Type Description

id*

string

The device ID being connected to the cradle.

cradleId

string

The ID of the cradle that is getting connected to the device.

manufacturer*

string

Device manufacturer

model* string Device model

distributor*

string

Device distributor

location

string

Device location

ipAddress* string Device IP address

* Mandatory parameter

Following is a sample request body.

Copy

Sample request body

{
    "id": "<device id>",
    "cradleId": "<cradle id>",
    "manufacturer": "<device manfacturer>",
    "model": "<device model>",
    "distributor": "<device distributor>",
    "location": "<device location>",
    "ipAddress": "<device ip>"
}

Request response

The response to the request is a JSON structure with the following fields:

  • taskId

  • status: Either NEW or IN_PROGRESS

Success response

Copy
Task is in progress
{
    "taskId": "b76ca9c8-9bc3-4da9-8a23-a324df92b6b1",
    "status": "IN_PROGRESS"
}

Error response

Copy
Status code 403: Forbidden
[
    {
        "userMessage": "Connect Device operation is not permitted for current user",
        "developerMessage": "1-668fbcb9-77fa3a2354bc6b9a5b6cd531"
    }
]
Copy
Status code 400: Bad Request
[
    {
        "userMessage": "Mandatory property 'Manufacturer' is missing",
        "developerMessage": "1-668e89e4-361917352b595e9920080c8c"
    }
]

Step 2 | Send a request to receive the device operation status

Use the following HTTP GET request to view the status of the connect device operation.

Method API

GET
Copy 
https://<your_cloud>.app.perfectomobile.com/api/v1/device-management/devices/task/<taskId>

Header parameters

Add the following header parameters to the request.

Name Description

Perfecto-Authorization

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

Request parameters

Name Type Description

taskId*

string

ID of the task that was returned by the initial API call

* Mandatory parameter

Request response

The response to the request is a JSON structure with the following fields:

  • taskId

  • status: Either IN_PROGRESS, COMPLETE or ERROR

  • result

Success response

Copy
Task is in progress
{
    "taskId": "010933e6-73d4-4238-b153-738dbe56caf6",
    "status": "IN_PROGRESS"
}
Copy
Task is complete
{
    "taskId": "010933e6-73d4-4238-b153-738dbe56caf6",
    "status": "COMPLETE",
    "result": "{\"data\":\"
    {\\\"id\\\":\\\"<device id>\\\",\\\"cradleHost
    \\\":\\\"<ip address of host>\\\",\\\"cradleId\\\":\\\"<cradle id>\\\"}\",\"meta\":
    {\"creationTime\":{\"formatted\":\"2024-06-
    26T08:58:51Z\",\"millis\":\"1719392331931\"},\"modelVersion\":\"1.1\",\"productVer
    sion\":\"master-SNAPSHOT\"}}"
}

Error response

Copy
Failed to connect to device
{
    "taskId": "ceea0054-0c0d-4d6e-ba04-fac6d1e90156",
    "status": "IN_ERROR",
    "error": {
        "userMessage": "Failed to connect device due to some internal server error. Please connect perfecto support for detail information"
    }
}