# Smarthands API Testing
This guide provides specific testing approaches and examples for the Equinix Smarthands API, building on the general [API Testing](https://docs.equinix.com/equinix-api/testing.md) principles.
## Smarthands API Overview
The Smarthands API allows you to programmatically request and manage various remote hands services in Equinix IBX data centers.
Here are the ECP API Mapping to the types of supported smarthands types:
| Smarthands Type | Description | ECP API Mapping |
| ---------------------------- | --------------------------------------------- | ---------------------------------------------------------------- |
| Request photos/documentation | Request cage-related photos or documentation | |
| SmartHand Other | Request a Smart Hands order not listed above | |
| SmartHand Cage Clean up | Request a cage clean up | |
| SmartHand Shipment Unpack | Unpack inbound shipment and dispose packaging | |
| SmartHand Cage Escort | Request IBX security escort | |
| Equipment Install | Request equipment installation | |
| Request Cables | Request cables | |
| Locate Packages | Request package location | |
| Run Patch Cables | Request cables run between devices | |
| Patch Cable Install | Request patch cable installation | |
| Move Patch Cable | Move patch cables between devices | |
| Patch Cable Removal | Remove patch cables | |
| Large SmartHands Order | Large cable/equipment requests | |
## Smarthands Testing Workflow
Before testing the Smarthands API, ensure you have:
* Valid API credentials with appropriate permissions
* Access to Equinix IBX locations where you have equipment
* Familiarity with the service ticket workflow
**Creating a Smarthands Service Request**
```
import requests
import json
# Setup authentication
auth_url = "https://api.equinix.com/oauth2/v1/token"
auth_payload = {
"grant_type": "client_credentials",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
}
auth_response = requests.post(auth_url, data=auth_payload)
token = auth_response.json()["access_token"]
# Test creating a Smarthands request
base_url = "https://api.equinix.com/v1"
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
}
# Example: Create a cage escort request
request_payload = {
"customerReferenceNumber": "RSS41244",
"purchaseOrder": {
"number": "123455",
"purchaseOrderType": "EXISTING"
},
"ibxLocation": {
"ibx": "AM1",
"cages": [
{
"cage": "AM1:01:001MC3",
"accountNumber": "12345",
"cabinets": [
"AM1:01:001MC3:0102"
]
}
]
},
"contacts": [
{
"contactType": "ORDERING",
"userName": "jondoe@test.com"
},
{
"contactType": "NOTIFICATION",
"userName": "jondoe@test.com"
},
{
"contactType": "TECHNICAL",
"name": "John Doe",
"workPhone": "1111111",
"workPhonePrefToCall": "ANYTIME",
"mobilePhone": "1111111",
"mobilePhonePrefToCall": "ANYTIME"
}
],
"schedule": {
"scheduleType": "STANDARD",
"requestedStartDate": "2017-04-05T12:00:00Z",
"requestedCompletionDate": "2017-04-05T12:00:00Z"
},
"attachments": [
{
"id": "eb9ab7e9-3785-41e4-af24-112dff",
"name": "eb9ab7e9-3785-41e4-af24-asfsa5424"
}
],
"serviceDetails": {
"durationVisit": "30 Minutes",
"openCabinetForVisitor": false,
"scopeOfWork": "Scope of work",
"supervisionReqForVisitor": false,
"workVisitOrderNumber": "1-108050984499"
}
}
create_response = requests.post(
f"{base_url}/orders/smarthands/cageEscort",
headers=headers,
data=json.dumps(request_payload)
)
# Verify response
assert create_response.status_code == 201, f"Failed to create request: {create_response.text}"
order_number = create_response.json()["OrderNumber"]
print(f"Successfully created Smarthands request with order number: {order_number}")
```
**Checking Request Status**
```
# Test retrieving request status
status_response = requests.get(
f"https://api.equinix.com/colocations/v2/orders/{order_number}",
headers=headers
)
assert status_response.status_code == 200, f"Failed to retrieve status: {status_response.text}"
status = status_response.json()["status"]
print(f"Current request status: {status}")
```
## Testing Error Scenarios
Always test error handling for your API implementation:
```
# Test with invalid location
invalid_payload = {
"customerReferenceNumber": "RSS41244",
"purchaseOrder": {
"number": "123455",
"purchaseOrderType": "EXISTING"
},
"ibxLocation": {
"ibx": "INVALID", # Invalid IBX code
"cages": [
{
"cage": "INVALID:01:001MC3",
"accountNumber": "12345",
"cabinets": [
"INVALID:01:001MC3:0102"
]
}
]
},
"contacts": [
{
"contactType": "ORDERING",
"userName": "jondoe@test.com"
}
],
"schedule": {
"scheduleType": "STANDARD",
"requestedStartDate": "2025-08-01T10:00:00Z",
"requestedCompletionDate": "2025-08-01T12:00:00Z"
},
"serviceDetails": {
"durationVisit": "30 Minutes",
"openCabinetForVisitor": false,
"scopeOfWork": "Test invalid IBX location",
"supervisionReqForVisitor": false
}
}
error_response = requests.post(
f"{base_url}/orders/smarthands/cageEscort",
headers=headers,
data=json.dumps(invalid_payload)
)
# Verify error response
assert error_response.status_code == 400, f"Expected error but got: {error_response.status_code}"
assert "Invalid IBX location" in error_response.text, "Error message not as expected"
```
## Best Practices for Smarthands API Testing
**Important Note**: The Equinix API is a production system that creates real shipment requests. Always follow these testing best practices to ensure you don't create unintended operational work.
1. **Set up a dedicated testing account**: Request a separate account for testing if possible
2. **Start with read-only operations**: Test GET endpoints first before creating/modifying resources
3. **Use clearly marked test requests**: Always prefix descriptions with "TEST:" to help operators identify test requests
4. **Clean up test resources**: Cancel any test shipments immediately after successful creation
5. **Include Complete Details**: Provide comprehensive information in your requests
6. **Tracking Numbers**: Always provide accurate tracking numbers for inbound shipments to ensure proper handling
7. **Contact Information**: Ensure the contact information is current and the person is available during the scheduled service window
8. **Description Details**: Be detailed but concise in describing requirements to help facility staff complete your request efficiently
## Automation Considerations
When building automation around the Smarthands API:
* Implement proper error handling and retries
* Consider implementing webhook receivers for status updates
* Build in validation for time windows and service availability
* Include audit logging of all API interactions
* Ensure tracking information is automatically included for all shipment-related requests
* Validate contact availability during scheduled service windows
## Additional Resources
* [Smart Hands Product Documentation](https://docs.equinix.com/smart-hands.md)
* [Smart Hands API Guides](https://docs.equinix.com/smart-hands/smart-hands-api/order-cage-escort.md)
* [Equinix API Authentication](https://docs.equinix.com/equinix-api/api-authentication.md)