Last updated: 05/08/2015

Using the API

Servo includes a simple REST-type API which enables other programs to communicate with the system.

Order status

The order status API allows you to programmatically query the database for the current status of a service order. You can then integrate this data to your webpage or CRM system. The order status API is public (it does not require authentication):

curl https://example.servoapp.com/api/status/?q=11012765

The response is returned as a JSON-encoded string:

{"status": "Awaiting parts", "timeline": [{"status": "Awaiting parts", "started_at": "2015-02-14T13:41:19.501856+00:00", "badge": "warning", "description": ""}, {"status": "In the service queue", "started_at": "2015-02-14T13:39:16.049317+00:00", "badge": "warning", "description": ""}], "status_description": "", "order": "11012765"}

Note: The "timeline" array is only available if you've enabled "Show timeline" under "Check-in" settings. The status_description field is taken from the description field of the status (configurable in the system settings). The "badge" field reflects the duration of the status compared to the time limits you've set in your status configuration with "success" meaning the age is within the set limits, "warning" - status age is nearing limits and "danger" meaning the age has exceeded the set limits.

Warranty lookups

To perform a warranty lookup for a device, generate an API token for a user (Settings > Users & Groups > Permissions) and then include that token in the authorization header of your request:

curl -H 'Authorization: Token 976f7492627e2c8ca3bfc77b9286db5097c69e57' https://example.servoapp.com/api/warranty/?sn=DGKFL06JDHJP

The response is returned as a JSON-encoded string:

{"description": "iMac (27-inch, Mid 2011)", "unlocked": null, "warranty_status": "OOW", "parts_and_labor_covered": false, "contract_end_date": null, "image_url": "", "sn": "DGKFL06JDHJP", "applied_activation_policy": "", "imei": "", "purchased_on": "2011-06-02", "fmip_active": false, "configuration": "IMAC 27\"/2.7QC/2X2GB/1TB/6770M"}

A single user account may have several API tokens so you can create one general API user and then use different tokens for different implementations. To revoke API access for an account, simply delete the account's API token(s).

Creating Service Orders

Orders can be created through the API using an authentication token and providing the order data as a JSON object in the request body. An example with curl would look like this:

curl -H 'Authorization: Token f2acb606f32bc3e0b2b03e0325ad17d1b084e6f4' http://localhost:8000/api/orders/ -d @create_order.json

create_order.json:

{
"problem": "Problem description goes here",
"customer": {
    "name": "Filipp Lepalaan",
    "email": "support@servoapp.com",
    "city": "Helsinki",
    "zip_code": "00500",
    "street_address": "Somestreet 19"
},
"attachment": {
    "name": "receipt.pdf",
    "data": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQgMCBvYmoKPDwgL0xlbmd0aCA1IDAgUiAvRmlsdGVyIC9GbGF0ZURlY29kZSA+PgpzdHJlYW0KeAErVAgEAAHnAOMKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjExCmVuZG9iagoyIDAgb2JqCjw8IC9UeXBlIC9QYWdlIC9QYXJlbnQgMyAwIFIgL1Jlc291cmNlcyA2IDAgUiAvQ29udGVudHMgNCAwIFIgL01lZGlhQm94IFswIDAgNTk1IDg0Ml0KPj4KZW5kb2JqCjYgMCBvYmoKPDwgL1Byb2NTZXQgWyAvUERGIF0gPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9NZWRpYUJveCBbMCAwIDU5NSA4NDJdIC9Db3VudCAxIC9LaWRzIFsgMiAwIFIgXSA+PgplbmRvYmoKNyAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMyAwIFIgPj4KZW5kb2JqCjggMCBvYmoKKFVudGl0bGVkKQplbmRvYmoKOSAwIG9iagooTWFjIE9TIFggMTAuOS41IFF1YXJ0eiBQREZDb250ZXh0KQplbmRvYmoKMTAgMCBvYmoKKEZpbGlwcCBMZXBhbGFhbikKZW5kb2JqCjExIDAgb2JqCigpCmVuZG9iagoxMiAwIG9iagooVGV4dEVkaXQpCmVuZG9iagoxMyAwIG9iagooRDoyMDE1MDUwODA4MjkxOFowMCcwMCcpCmVuZG9iagoxNCAwIG9iagooKQplbmRvYmoKMTUgMCBvYmoKWyAoKSBdCmVuZG9iagoxIDAgb2JqCjw8IC9UaXRsZSA4IDAgUiAvQXV0aG9yIDEwIDAgUiAvU3ViamVjdCAxMSAwIFIgL1Byb2R1Y2VyIDkgMCBSIC9DcmVhdG9yIDEyIDAgUgovQ3JlYXRpb25EYXRlIDEzIDAgUiAvTW9kRGF0ZSAxMyAwIFIgL0tleXdvcmRzIDE0IDAgUiAvQUFQTDpLZXl3b3JkcyAxNSAwIFIKPj4KZW5kb2JqCnhyZWYKMCAxNgowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDA2NDEgMDAwMDAgbiAKMDAwMDAwMDEyNSAwMDAwMCBuIAowMDAwMDAwMjY4IDAwMDAwIG4gCjAwMDAwMDAwMjIgMDAwMDAgbiAKMDAwMDAwMDEwNyAwMDAwMCBuIAowMDAwMDAwMjI5IDAwMDAwIG4gCjAwMDAwMDAzNTEgMDAwMDAgbiAKMDAwMDAwMDQwMCAwMDAwMCBuIAowMDAwMDAwNDI2IDAwMDAwIG4gCjAwMDAwMDA0NzcgMDAwMDAgbiAKMDAwMDAwMDUxMSAwMDAwMCBuIAowMDAwMDAwNTMwIDAwMDAwIG4gCjAwMDAwMDA1NTcgMDAwMDAgbiAKMDAwMDAwMDU5OSAwMDAwMCBuIAowMDAwMDAwNjE4IDAwMDAwIG4gCnRyYWlsZXIKPDwgL1NpemUgMTYgL1Jvb3QgNyAwIFIgL0luZm8gMSAwIFIgL0lEIFsgPDRlMGI4Y2UyZmEzNjdkZjU4MThjOGE4ZjBiYTczZDM1Pgo8NGUwYjhjZTJmYTM2N2RmNTgxOGM4YThmMGJhNzNkMzU+IF0gPj4Kc3RhcnR4cmVmCjgxNAolJUVPRgo="
},
"device": {
    "sn": "11112222333344445555",
    "description": "MacBook Pro",
    "accessories": ["Power adapter"]
}

}

A breakdown of the fields:

FieldExplanationExampleRequired
problem A problem description for this order. Creates a note. Does not work Yes
customer.name Name of customer Johnny Appleseed Yes
customer.email e-mail address of customer support@servoapp.com Yes
customer.phone Phone number of customer 3584521023124 No
customer.city City of customer Helsinki No
customer.zip_code Postal code 00500 No
customer.street_address Postal address Somestreet 19 No
attachment.name Name of attached file receipt.pdf No
attachment.data An attachment to go with the problem description BASE64-encoded data No
device.sn Serial number or IMEI code of serviced device 1111111111 No
device.description Description of device MacBook Pro No
device.accessories List of accessories supplied with the device ["power adapter", "second skin"] No