Updating a job using the Okappy API

Okappy is a connected field service management platform where you can connect to your customers, employees and subcontractors. Send and receive jobs and see the status of those jobs as they are updated by your employees or subcontractors.

This guide shows how to update an existing job using the Okappy API.

Authentication

First you will need to get an up to date authentication token.

For further information see authenticating with Okappy.

Updating a job

To update a job, send a PUT request to the job endpoint with the Okappy job ID in the URL.

PUT jobs/JOB_ID

Replace JOB_ID with the ID of the job you want to update.

Headers

Updating one field

For a simple update, send one field in the request body. This is useful when you only need to change one piece of job information, such as the job status, priority, description, appointment date or address.

Example request

curl -X PUT "https://api.okappy.com/rest/v2/jobs/12345"   -H "Authorization: YOUR_ACCESS_TOKEN"   -H "Content-Type: application/json"   --data-binary @job-update.json

Example job-update.json:

Example response

Updating the full job record

You can also send a fuller job payload. The API expects the core allocation and status fields to be included when more than one field is supplied.

Example request body

Example curl request

curl -X PUT "https://api.okappy.com/rest/v2/jobs/12345"   -H "Authorization: YOUR_ACCESS_TOKEN"   -H "Content-Type: application/json"   --data-binary @job-update-full.json

Required fields for full updates

When sending more than one field, include the following fields:

Field	Description
allocatedUserID	The Okappy user ID of the employee allocated to the job. Use -1 if not allocating to an employee.
subContractorID	The Okappy company ID of the subcontractor allocated to the job. Use -1 if not allocating to a subcontractor.
createdBy	The Okappy customer/company ID that created or owns the job.
jobPriority	The job priority, for example Normal, High or another priority configured on your account.
jobStatus	The new job status, for example In progress, Completed or another status configured on your account.
detailsWorkDone	Notes or work done details to store against the job.
dateCompleted	The completion date/time. Use TimeNow to use the current time where appropriate.

Optional fields

Common optional fields include:

Field	Description
customerReference	Your own job reference.
createdByName	The name of the company or source that created the job.
actingContactName	Main contact name for the job.
actingContactInformation	Additional contact information.
policyHolderFirstName	Policy holder first name.
policyHolderLastName	Policy holder last name.
policyHolderTelephone	Main telephone number.
policyHolderMobile	Mobile number.
alternativeTelephone	Alternative telephone number.
address1	First line of the job address.
address2	Second line of the job address.
address3	Third line or postcode for the job address.
dbRequiredBy	Appointment start date/time.
dbRequiredByEnd	Appointment end date/time.
jobType	Job template/type ID.
jobDescription	Description of the work required.
incidentType	Incident type.
roomsAffected	Rooms affected.
healthSafety	Health and safety notes.
propertyType	Property type.
jobCostRate	Job cost/rate value.
extra	Additional information field.
column1 to column5	Additional custom job fields.

Status and errors

A successful update returns:

If the update fails, the response includes status: "failed" and an error message.

Common reasons for errors include:

• The token is missing, expired or invalid.
• The job ID does not exist.
• The job belongs to a different customer account.
• A required field is missing from a full update payload.
• A field contains a value that cannot be converted to the expected type, such as a non-numeric user ID.

Notes

• The API checks that the job belongs to the authenticated customer’s account before updating it.
• For simple changes, send one field only. This avoids having to supply the full set of required update fields.
• Field names are case-sensitive. Use the field names shown in this guide.
• Appointment dates should be supplied in yyyy-MM-dd HH:mm:ss format.
• jobStatus maps to the job’s status field in Okappy.
• alternativeTelephone maps to the alternate telephone field in Okappy.