Creating a job template using the Okappy API
Okappy is a connected field service management platform where you can connect to your customers, employees and subcontractors, create jobs and assign those jobs to the right person or company.
This guide shows how to create a new job template using the Okappy API. A job template controls the job sheet used when creating jobs, including the job type name, fields shown on the job and options such as signature, payment and alert settings.
Authentication
First you will need to get an up to date authentication token. For further information see authenticating with Okappy.
Creating a job template
To create a job template, send a POST request to the job templates endpoint.
POST /jobs/templates
The full URL is:
https://api.okappy.com/rest/v2/jobs/templates
Headers
| Header | Content |
|---|---|
| Authorization | Bearer token |
| Content-Type | application/json |
The token should be the string from the access_token field returned by an authentication request.
Example request
Body data
The body data should contain a JSON object. The main field is customTemplate, which contains the template definition. The API requires customTemplate.jobSheet and customTemplate.jobSheet.name.
The example below creates a template called Drainage callout with two simple fields.
Some integrations serialize the template as a JSON string. The API also accepts that shape because the server parses the customTemplate value before creating the template.
Fields
The request is made up of the following fields.
customTemplate – required
The job template definition. This should include a jobSheet object. The API accepts this either as a JSON object or as a JSON string.
jobSheet.name – required
The name of the job template. This is the job type name shown in Okappy. Long names are shortened by the server when saved.
jobSheet.groups
The groups and fields shown on the job sheet. Use the same structure returned by the template builder or the retrieve templates endpoint.
jobSheet.options
Optional template settings such as signature, payment, alert timings and whether on-site or completed times are shown.
customChecksheet
Set this to 0 for a normal job template. Other values are used internally for custom checksheet modes.
style / Style
Optional custom CSS or style content for the template.
js / JS
Optional custom JavaScript content for the template.
Template options
The following options can be supplied inside customTemplate.jobSheet.options. If an option is omitted, Okappy uses the default shown in brackets.
signature_mandatory (false) – whether a signature is mandatory.
payment_required (false) – whether payment is required for jobs using the template.
job_duration (60) – default job duration in minutes.
alert_if_not_viewed (60) – first alert timing if the job has not been viewed, in minutes.
second_alert_if_not_viewed (120) – second alert timing if the job has not been viewed, in minutes.
alert_if_not_on_site (60) – first alert timing if the job has not moved on site, in minutes.
second_alert_if_not_on_site (120) – second alert timing if the job has not moved on site, in minutes.
alert_if_not_completed (1440) – alert timing if the job has not been completed, in minutes.
show_on_site_time (false) – whether to show the on-site time.
show_completed_time (false) – whether to show the completed time.
link_from_invoice (false) – whether jobs using this template can be linked from invoices.
message (blank) – optional message for the template.
messageOnDay (blank) – optional message shown on the day.
images_mandatory (false) – whether images are mandatory.
Responses
200 – operation successful. The response includes the new jobTypeId.
400 – bad request, such as no template in the request or no job template name.
401 – unauthorised.
415 – data sent in the wrong format. Send JSON with Content-Type: application/json.
429 – too many requests in a short period of time. Please try again later.
500 – the server could not create the template.
Success response
Error response
Using the new template
When the request succeeds, Okappy returns the new jobTypeId. Use that ID as the job type when creating jobs with the API. You can also retrieve your templates again using Retrieving job templates to confirm the template is available.