Project Description

Creating a job using the Okappy API

Okappy is a B2B workforce management platform consisting of companies, employees and devices.  Companies can connect to customers, subcontractors and employees. Add jobs and then assign those jobs to an employee or subcontractor.

To create a job using the Okappy API, follow the instructions below

Authentication

First you will need to get an up to date authentication token.  For further information see authenticating with Okappy.

Creating a job

Add a job using the following endpoint.

POST /jobs

Headers

Header Content
Authorize Bearer token

The token should be a string taken from the “access_token” field of a response to an authorise request.

Parameters

No parameters

Body data

The body data of the request should contain a JSON object but sent with content type text/plain. It should have the following basic structure:

{
"Name" : "Joe Bloggs",
"Reference" : "PO 34534",
"Address1" : "35 Kingsland Road, London, E2 8AN",
"Telephone" : "0207 099 5698",
"Description" : "Check boiler and repair if required"
}

The following table lists the fields that may be present in the body data:

Name Content Required
CustomerReference A reference for the job No
createdById ID for your customer No
CustomerName Name of your customer No
CreatedBy The name of the person who raised the job No
Name A contact name for the job No
Address1 A primary address for the job in the format 10 Downing Street, London, WC1 No
Address2 A secondary address for the job in the format 10 Downing Street, London, WC1 No
Address3 An additional address for the job in the format 10 Downing Street, London, WC1 No
Telephone A telephone number for the job No
Mobile A mobile phone number for the job No
Phone2 An additional phone number for the job No
Priority The job’s priority No
Description The description of the job No
MediumField1 A medium field corresponding to medium field 1 in your job template No
MediumField2 A medium field corresponding to medium field 2 in your job template No
MediumField3 A medium field corresponding to medium field 3 in your job template No
MediumField4 A medium field corresponding to medium field 4 in your job template No
MediumField5 A medium field corresponding to medium field 5 in your job template No
MediumField6 A medium field corresponding to medium field 6 in your job template No
MediumField7 A medium field corresponding to medium field 7 in your job template No
MediumField8 A medium field corresponding to medium field 8 in your job template No
LargeField1 A large field corresponding to large field 1 in your job template No
LargeField2 A large field corresponding to large field 3 in your job template No
SmallField1 A small field corresponding to small field 1 in your job template No
SmallField2 A small field corresponding to small field 2 in your job template No
SmallField3 A small field corresponding to small field 3 in your job template No
SmallField4 A small field corresponding to small field 4 in your job template No
SmallField5 A small field corresponding to small field 5 in your job template No
StartDateTime Start time of the job, in the format yyyy-mm-dd h:mm No
EndDateTime Start time of the job, in the format yyyy-mm-dd h:mm No

Notes:

  • You can provide the connection id and/or customer name of your customer, otherwise the job will default to yourself.
  • You can retrieve your connection id using the connections endpoint.
  • If the customer name is provided, please ensure it matches your customers name including position of any spaces and spelling. Capitalisation does not matter.
  • If both a connection id and customer name is provided, the customer name will take precedence.

Reference: For further information about creating jobs with a template, see https://www.okappy.com/support-article/creating-job-templates/

Response

Code Description
200 Operation successful
400 Bad request
401 Unauthorised
415 Data sent in wrong format (should be JSON)
429 Too many requests in a short period of time (please try again later)