Attaching files to a Job Diary

A note on file attachments

The Attachment endpoint provides access to all file attachments within an account, including photos, PDF’s and other user-attached files.

Step-by-step guide

To attach a file to a job the following steps are required:

Create a job record
Create a new attachment record
Submit the binary data for the attachment

1. Create the job record

<?php

$data = [
  "status" => "Quote",
  "job_address" => "1 Infinite Loop, Cupertino, California 95014, United States",
  "job_description" => "Client has requested quote for service delivery"
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.servicem8.com/api_1.0/Job.json');
curl_setopt($ch, CURLOPT_USERPWD, "email:password");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Content-Type: application/json',
  'Accept: application/json'
]);

$response = curl_exec($ch);
list($strHeaders, $strBody) = explode("\r\n\r\n", $response, 2);
$arrHeaders = explode("\r\n", $strHeaders);
$strJobUUID = false;
foreach($arrHeaders as $strHeader) {
	list($strHeaderKey, $strHeaderValue) = explode(": ", $strHeader);
	if($strHeaderKey == 'x-record-uuid') {
		$strJobUUID = $strHeaderValue;
	}
}

echo "Created Job Record with UUID '$strJobUUID'\n".$strBody;

curl -u email:password 
-H "Accept: application/json" 
-d '{"status": "Quote", "job_address":"1 Infinite Loop, Cupertino, California 95014, United States","description":"Client has requested quote for service delivery"}' 
-X POST https://api.servicem8.com/api_1.0/job.json

This creates a new job, with a description, contact and job address.

Response

Status: 200
x-record-uuid: 8936d9f2-7bcc-4fc3-b83a-d18987fcf30b

{"errorCode":0,"message":"OK"}

📘
Review the response for the x-record-uuid header, as this will contain the UUID for the newly created job.

2. Create the attachment record

Creates a new Attachment.

related_object must be set to “job”
related_object_uuid must be set to the UUID for your newly created job record.
file_type must match the file you plan on uploading, including full stop, eg. “.pdf”

Request

<?php

$data = [
  "related_object" => "job",
  "related_object_uuid" => "8936d9f2-7bcc-4fc3-b83a-d18987fcf30b",
  "attachment_name" => "Test.pdf",
  "file_type" => ".pdf",
  "active" => true
]; 

$ch = curl_init();                                                          
curl_setopt($ch, CURLOPT_URL, 'https://api.servicem8.com/api_1.0/Attachment.json');    
curl_setopt($ch, CURLOPT_USERPWD, "email:password");        
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Content-Type: application/json',
  'Accept: application/json'
]);
	                                
$response = curl_exec($ch);
list($strHeaders, $strBody) = explode("\r\n\r\n", $response, 2);
$arrHeaders = explode("\r\n", $strHeaders);
$strAttachmentUUID = false;
foreach($arrHeaders as $strHeader) {
	list($strHeaderKey, $strHeaderValue) = explode(": ", $strHeader);
	if($strHeaderKey == 'x-record-uuid') {
		$strAttachmentUUID = $strHeaderValue;
	}
}

echo "Created Attachment Record with UUID '$strAttachmentUUID'\n".$strBody;

POST https://api.servicem8.com/api_1.0/Attachment.json

{
"related_object":"job",
"related_object_uuid": "8936d9f2-7bcc-4fc3-b83a-d18987fcf30b",
"attachment_name": "Test.pdf",
"file_type": ".pdf",
"active": true
}

Response

Status: 200
x-record-uuid: 2404fbd2-cff6-4222-86b4-54a6ea4dbb8b

{"errorCode":0,"message":"OK"}

📘
Once again, review the response for the x-record-uuid, as this will contain the uuid for the newly created attachment record.

3. Submit the file attachment data

Submit your file using endpoint (with the UUID provided to you during the attachment record response).

This will attach the file to the attachment record, making it available via API and via the job diary for the specified job record.

Request

<?php

$strFullPathFileToUpload = '/path/to/file/test.pdf';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.servicem8.com/api_1.0/Attachment/2404fbd2-cff6-4222-86b4-54a6ea4dbb8b.file');
curl_setopt($ch, CURLOPT_USERPWD, 'email:password');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Accept: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, ['file' => new CurlFile($strFullPathFileToUpload)]);

$response = curl_exec($ch);
echo $response;

POST https://api.servicem8.com/api_1.0/Attachment/2404fbd2-cff6-4222-86b4-54a6ea4dbb8b.file

Response

Status: 200

{"errorCode":0,"message":"OK"}