This API allows dealers to pull their 30 most recently completed inspections from catinspect.com, in either XML or JSON format. Access to the API is secured with a dealer-specific token that must be generated by a dealer admin. This document describes how to generate that token, make the API request, and interpret the results.
Any dealer admin who is logged on to catinspect.com can generate the unique token for his dealer. Choose the Settings option from the toolbar at the top right and you'll see an area on your settings page labeled API Key. Initially, its contents will be empty. Click the Generate button to generate a key. You'll see it displayed next to the button.
Once your key has been generated, you can change it at any time by clicking Regenerate or remove it completely by clicking Delete. Keep in mind that changing or deleting the key takes effect immediately, and your old key will stop working.
Once you have a key, you can use it to access recently completed inspections at these URLs:
For XML data: http://catinspect.com/api/v1/inspections.xml?api_key=**[API_KEY]**
For JSON data: http://catinspect.com/api/v1/inspections.json?api_key=**[API_KEY]**
Make sure to include your API key as the url parameter, replacing the [API_KEY] placeholder. The response will be a list of recently completed inspections, limited to a maximum of 30 inspections. If you have no completed inspections, you'll see an empty response.
Below is an example of the XML returned. Note that here we have just one completed inspection to keep the example shorter, and that the inspection has only two subsections, each containing one field. A real inspection will certainly be much longer. Sections and subsections can be nested to any depth, and fields are not guaranteed to include a response. Missing responses indicate fields that the inspector left blank.
<inspections type="array">
<inspection>
<uuid>893dd47c-4222-4ab5-9c2f-64a0d80b4a77</uuid>
<name>TA-1</name>
<type>TA-1</type>
<updated-at type="datetime">2012-04-13T17:03:41Z</updated-at>
<user>
<username>inspectionsdealer</username>
<name>Dealer Inspector</name>
</user>
<sections type="array">
<section>
<heading>Visual Inspection</heading>
<sections type="array">
<section>
<heading>General Appearance</heading>
<fields type="array">
<field>
<prompt>Radiator Grill & Shroud</prompt>
<type>select</type>
<response>
<uuid>cb061f9f-2477-4c5d-b044-cad3d083018c</uuid>
<value>N/A</value>
<updated-at type="datetime">2012-04-13T17:03:41Z</updated-at>
</response>
<options type="array">
<option>
<name>N/A</name>
</option>
<option>
<name>Poor</name>
<abbreviation>P</abbreviation>
</option>
<option>
<name>Fair</name>
<abbreviation>F</abbreviation>
</option>
<option>
<name>Good</name>
<abbreviation>G</abbreviation>
<image>
<uuid>03e3e042-3f22-4115-a6ca-35b4816cec36</uuid>
<urls>
<large>
https://catinspect.s3.amazonaws.com/uploads/options/03e3e042-3f22-4115-a6ca-35b4816cec36/large_image.jpg
</large>
<thumbnail>
https://catinspect.s3.amazonaws.com/uploads/options/03e3e042-3f22-4115-a6ca-35b4816cec36/thumbnail_image.jpg
</thumbnail>
</urls>
<updated-at type="datetime">2012-04-09T13:37:26Z</updated-at>
</image>
</option>
<option>
<name>Very Good</name>
<abbreviation>VG</abbreviation>
</option>
<option>
<name>New</name>
<abbreviation>N</abbreviation>
</option>
</options>
</field>
</fields>
</section>
<section>
<heading>Safety Items</heading>
<fields type="array">
<field>
<prompt>Tire Pressure</prompt>
<type>input</type>
<response>
<uuid>54a2d256-a17f-42e6-acea-8e6d026f9a63</uuid>
<value>One of the tires is flat. You have to guess which one.</value>
<updated-at type="datetime">2012-04-13T17:03:41Z</updated-at>
<images>
<image>
<uuid>85ed890e-1892-ac98-8e7a-8971e658eab3</uuid>
<urls>
<large>
https://catinspect.s3.amazonaws.com/uploads/responses/85ed890e-1892-ac98-8e7a-8971e658eab3/large_image.png
</large>
<thumbnail>
https://catinspect.s3.amazonaws.com/uploads/responses/85ed890e-1892-ac98-8e7a-8971e658eab3/thumbnail_image.png
</thumbnail>
</urls>
<updated-at type="datetime">2012-04-09T13:37:26Z</updated-at>
</image>
</images>
</response>
</field>
</fields>
</section>
</sections>
</section>
</sections>
</inspection>
</inspections>
The first field in this example is a multiple choice ("select") type field, and so it lists all of its choices in addition to the inspector's chosen response. Note that one of those options has an image attached and that image is listed in different sizes, each with a URL.
The second field in the sample inspection is a text entry field. Therefore, it doesn't list any options, and the response includes the free-form text that was entered by the inspector. Any response can also include images that the inspector attached, and this response shows an example of that as well.
Below is the same response from the XML example, but in JSON format. We've added newlines and indentation to make the sample easier to read. The actual response is a single line.
[
{
"uuid":"893dd47c-4222-4ab5-9c2f-64a0d80b4a77",
"name":"TA-1",
"type":"TA-1",
"updated-at":{"@type":"datetime","$":"2012-04-13T17:03:41Z"},
"user":{"name":"Dealer Inspector","username":"inspectionsdealer"},
"sections":
[
{
"heading":"Visual Inspection",
"sections":
[
{
"heading":"General Appearance",
"fields":
[
{
"prompt":"Radiator Grill & Shroud",
"type":"select",
"response":{
"uuid":"cb061f9f-2477-4c5d-b044-cad3d083018c",
"value":"N/A",
"updated-at":{"@type":"datetime","$":"2012-04-13T17:03:41Z"}
},
"options":
[
{"name":"N/A","abbreviation":null},
{"name":"Poor","abbreviation":"P"},
{"name":"Fair","abbreviation":"F"},
{
"name":"Good","abbreviation":"G",
"image":{
"uuid":"03e3e042-3f22-4115-a6ca-35b4816cec36",
"urls":{
"large":"https://catinspect.s3.amazonaws.com/uploads/options/03e3e042-3f22-4115-a6ca-35b4816cec36/large_image.jpg",
"thumbnail":"https://catinspect.s3.amazonaws.com/uploads/options/03e3e042-3f22-4115-a6ca-35b4816cec36/thumbnail_image.jpg"
},
"updated_at":{"@type":"datetime","$":"2012-04-09T13:37:26Z"}
}
},
{"name":"Very Good","abbreviation":"VG"},
{"name":"New","abbreviation":"N"}
]
},
}
]
},
{
"heading":"Safety Items",
"fields":
[
{
"prompt":"Tire Pressure",
"type":"input",
"response":{
"uuid":"54a2d256-a17f-42e6-acea-8e6d026f9a63",
"value":"One of the tires is flat. You have to guess which one.",
"updated-at":{"@type":"datetime","$":"2012-04-13T17:03:41Z"},
"images":
[
{
"uuid":"85ed890e-1892-ac98-8e7a-8971e658eab3",
"urls":{
"large":"https://catinspect.s3.amazonaws.com/uploads/responses/85ed890e-1892-ac98-8e7a-8971e658eab3/large_image.png",
"thumbnail":"https://catinspect.s3.amazonaws.com/uploads/responses/85ed890e-1892-ac98-8e7a-8971e658eab3/thumbnail_image.png"
},
"updated-at":{"@type":"datetime","$":"2012-04-09T13:37:26Z"}
}
]
}
}
]
}
]
}
]
}
]