Assigning 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 assign those jobs to an employee or subcontractor.

This guide shows how to assign or reassign 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.

Assigning a job

To assign a job, send a PUT request to the assignment endpoint.

PUT /jobs/assign

The request body must include the job ID and either an employee user ID or a subcontractor company ID.

Headers

Assigning a job to an employee

Use allocatedUserID when assigning the job to an employee on your Okappy account. Set subContractorID to -1.

Example request

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

Example assign-job.json:

Example response

Assigning a job to a subcontractor

Use subContractorID when assigning the job to a subcontractor company connected to your account. Set allocatedUserID to -1.

Example request

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

Example assign-subcontractor-job.json:

Example response

Reassigning a job

When reassigning a job, you can include the previous employee or subcontractor so they can be notified that the job has been reassigned.

Example request body

If the previous assignee was a subcontractor, set originalSubcontractorID and use -1 for originalUserID.

Required fields

Field	Description
jobID	The Okappy job ID of the job to assign.
allocatedUserID	The Okappy user ID of the employee to assign the job to. Use -1 when assigning to a subcontractor.
subContractorID	The Okappy company ID of the subcontractor to assign the job to. Use -1 when assigning to an employee.

At least one of allocatedUserID or subContractorID must be a valid positive ID.

Optional fields

Field	Description
originalUserID	The previous employee user ID. Include this when reassigning from an employee.
originalSubcontractorID	The previous subcontractor company ID. Include this when reassigning from a subcontractor.
textOriginalSubcontractor	Use Y to request a text notification to the original subcontractor. Defaults to N.
textNewSubcontractor	Use Y to request a text notification to the new subcontractor. Defaults to N.
telephoneNumber	Telephone number used when sending a subcontractor text notification.
allocationPublic	Set to true to mark the job allocation as public. Defaults to false.

Status and errors

A successful assignment returns:

If the assignment 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 is missing or invalid.
• The job belongs to a different customer account.
• Neither allocatedUserID nor subContractorID was supplied as a valid ID.
• The employee or subcontractor ID does not exist or is not available to your account.

Notes

• The API checks that the job belongs to the authenticated customer’s account before assigning it.
• Assigning to an employee and assigning to a subcontractor use the same endpoint.
• Use -1 for the assignee type that is not being used.
• Reassigning a job updates the job allocation and adds an audit trail entry for the reassignment.
• Okappy sends push notifications when relevant previous assignee details are supplied.