Jobs

Jobs in Kojo are the top level organization for construction, service or maintenance projects that your company is working on. In some external systems they may also be called "Projects" (Procore, PlanGrid). Other systems may have "Work Orders" (COINS) or "Service Jobs" (Sage) or use a "type" field to indicate special project types, but Kojo does not make such a distinction. These concepts should map directly to Jobs in Kojo.

important

If your system uses "sub-jobs" to classify job phases, the Phase entity in Kojo should be used.

Schema

`Job`

Name	Type	Description	Example
id	`ID`	The unique job ID	`"ckmnpybisiy5x08abky4g2d1f"`
code	`string`	A unique human-readable code to represent this job	`01-300`
createdAt	`DateTime`	When this job was created	`"2021-03-24 17:26:46.983Z"`
defaultLocation	`Location?`	The default location for orders associated with this job	See `Location` docs
defaultTaxCode	`TaxCode?`	The default tax code to use for orders associated with this job	See `TaxCode` docs
name	`string`	The job name	`"Salesforce Tower 32nd Floor"`
startDate	`DateTime?`	When this job was started	`"2021-03-24 17:26:46.983Z"`
state	`JobState`	The current state of the job	`OPEN`
updatedAt	`DateTime`	When this job was last modified	`"2021-03-24 17:26:46.983Z"`

Enums

`JobState`

Value	Description
OPEN	The job is currently active.
CLOSED	The job has been closed or cancelled

REST Endpoints

GET `/jobs`

Read all jobs, with pagination.

Parameters

Accepts all standard pagination parameters.

Allowed orderBy fields: code, createdAt, id, name, startDate, updatedAt.

Allowed filter fields: code, createdAt, id, name, startDate, state, updatedAt.

Response

A list of Job objects.

Example Request

GET https://api.kojo.tech/jobs?limit=10&offset=20

Example Response

[
  {
    "code": "01-300",
    "createdAt": "2021-03-24 17:26:46.983Z",
    "defaultLocation": null,
    "defaultTaxCodeId": "cl478y6iq45873i4xc4ldfwir",
    "id": "ckmnpybisiy5x08abky4g2d1f",
    "name": "Salesforce Tower 32nd Floor",
    "startDate": null,
    "state": "OPEN",
    "updatedAt": "2021-03-24 17:26:46.983Z"
  },
  {
    "code": "01-301",
    "createdAt": "2021-03-24 17:26:46.983Z",
    "defaultLocation": "cl478y6iq45873i4xc4ldfwir",
    "defaultTaxCodeId": null,
    "id": "ckmnpybi7ag5x08abky4g2d1f",
    "name": "Chase Center NE",
    "startDate": null,
    "state": "OPEN",
    "updatedAt": "2021-03-24 17:26:46.983Z"
  }
]

POST `/jobs`

Creates a new job.

Parameters

Name	Type	Description	Example
code	`string`	A unique human-readable code to represent this job	`01-300`
defaultLocationId	`ID`	The id of default location for orders associated with this job	`"ckmnpybisiy5x08abky4g2d1f"`
defaultTaxCodeId	`ID`	The id of the default tax code to use for orders associated with this job	`"ckmnpybisiy5x08abky4g2d1f"`
name	`string`	The job name	`"Salesforce Tower 32nd Floor"`
startDate	`DateTime?`	When this job was started	`"2021-03-24 17:26:46.983Z"`
state	`JobState`	The current state of the job	`OPEN`

Response

The created Job.

Example Request

POST https://api.kojo.tech/jobs
{
  "code": "01-300",
  "name": "Salesforce Tower 32nd Floor"
}

Example Response

{
  "code": "01-300",
  "createdAt": "2021-03-24 17:26:46.983Z",
  "defaultLocationId": "cl478y6gc44873i4x52s5w1tu",
  "defaultTaxCodeId": "cl478y6j045973i4xd4yx5ads",
  "id": "ckmnpybisiy5x08abky4g2d1f",
  "name": "Salesforce Tower 32nd Floor",
  "startDate": null,
  "state": "OPEN",
  "updatedAt": "2021-03-24 17:26:46.983Z"
}

POST `/jobs/batch`

Creates or Updates jobs in batches.

warning

Batch endpoints will accept at most 1000 elements per request.

Parameters

Name	Type	Description
inputs	`UpsertJobsInput[]`	A list of at most 1000 jobs for upsert

Upsert Jobs Input

Name	Type	Description	Example
code	`string`	The code of the job to update.	`"01-100"`
name	`string`	The job name	`"Salesforce Tower 32nd Floor"`
defaultLocationId	`ID?`	The id of default location for orders associated with this job	`"ckmnpybisiy5x08abky4g2d1f"`
defaultTaxCodeId	`ID?`	The id of the default tax code to use for orders associated with this job	`"ckmnpybisiy5x08abky4g2d1f"`
state	`JobState?`	The current state of the job	`OPEN`
startDate	`DateTime?`	When this job was started	`"2021-03-24 17:26:46.983Z"`

Response

A list of Jobs.

Example Request

POST https://api.kojo.tech/jobs/batch
{
  "inputs": [
    {
    "code": "01-300",
    "name": "Salesforce Tower 32nd Floor"
    },
    {
    "code": "01-301",
    "name": "Oracle Tower"
    }
  ]
}

Example Response

[
  {
    "code": "01-300",
    "id": "ckmnpybisiy5x08abky4g2d1f",
    "name": "Salesforce Tower 32nd Floor",
    "startDate": null,
    "state": "OPEN",
    "createdAt": "2021-03-24 17:26:46.983Z",
    "updatedAt": "2021-03-24 17:26:46.983Z"
  },
  {
    "code": "01-301",
    "id": "ckmnpybisiy5x08abky4g2d1a",
    "name": "Oracle Tower",
    "startDate": null,
    "state": "OPEN",
    "createdAt": "2021-03-24 17:26:46.983Z",
    "updatedAt": "2021-03-24 17:26:46.983Z"
  }
]

GET `/jobs/:idOrCode`

Read a single job by ID or code.

Parameters

Name	Description	Example
id	The ID of the job to fetch	`"ckmnpybisiy5x08abky4g2d1f"`
code	The job code of the job to fetch	`"01-100"`

Response

A single Job object.

Example Request

GET https://api.kojo.tech/jobs/01-300

Example Response

{
  "code": "01-300",
  "createdAt": "2021-03-24 17:26:46.983Z",
  "defaultLocationId": null,
  "defaultTaxCodeId": "cl478y6iq45873i4xc4ldfwir",
  "id": "ckmnpybisiy5x08abky4g2d1f",
  "name": "Salesforce Tower 32nd Floor",
  "startDate": null,
  "state": "OPEN",
  "updatedAt": "2021-03-24 17:26:46.983Z"
}

PATCH `/jobs/:idOrCode`

Updates a job. You must specify either the job ID or the job code.

Parameters

Name	Type	Description	Example
id	`ID`	The ID of the job to update.	`"ckmnpybisiy5x08abky4g2d1f"`
code	`string`	The code of the job to update. If both `id` and `code` are provided, the job's code will be updated to this value.	`"01-100"`
defaultLocationId	`ID`	The id of default location for orders associated with this job	`"ckmnpybisiy5x08abky4g2d1f"`
defaultTaxCodeId	`ID`	The id of the default tax code to use for orders associated with this job	`"ckmnpybisiy5x08abky4g2d1f"`
name	`string?`	The job name	`"Salesforce Tower 32nd Floor"`
state	`JobState?`	The current state of the job	`OPEN`
startDate	`DateTime?`	When this job was started	`"2021-03-24 17:26:46.983Z"`

Response

The updated Job.

Example Request

PATCH /jobs/01-300
{
  "name": "Salesforce Tower 32nd Floor"
}

Example Response

{
  "code": "01-300",
  "createdAt": "2021-03-24 17:26:46.983Z",
  "defaultLocationId": null,
  "defaultTaxCodeId": "cl478y6iq45873i4xc4ldfwir",
  "id": "ckmnpybisiy5x08abky4g2d1f",
  "name": "Salesforce Tower 32nd Floor",
  "startDate": null,
  "state": "OPEN",
  "updatedAt": "2021-03-24 17:26:46.983Z"
}

GET `/jobs/:idOrCode/locations`

Read locations on a specific job.

Parameters

See Location pagination parameters

Response

A list of Location objects.

Example Request

GET https://api.kojo.tech/jobs/01-100/locations?limit=10

Example Response

[
  {
    "addressLine1": "415 Mission St",
    "addressLine2": null,
    "city": "San Francisco",
    "createdAt": "2021-03-24 17:26:46.983Z",
    "directions": "Approach from the east on Howard St, turn right at \"Deliveries\" sign.",
    "id": "ckmnpybixiy5y0817spfhmj78",
    "latitude": null,
    "longitude": null,
    "name": "Salesforce Tower Rear Entrance",
    "phone": null,
    "type": "Jobsite",
    "updatedAt": "2021-03-24 17:26:46.983Z",
    "zipcode": "94105"
  }
]

POST `/jobs/:idOrCode/locations`

Add a location to a specific job.

Parameters

Name	Type	Description	Example
locationId	`ID`	The ID of the location to add to the job	`"ckmnpybisiy5x08abky4g2d1f"`
shouldSetAsDefault	`boolean`	Set true if the location should be configured as the default location for the job.	`true`

Response

The updated Job object.

Example Request

POST https://api.kojo.tech/jobs/01-300/locations?locationId=ckmnpybisiy5x08abky4g2d1f&shouldSetAsDefault=true

Example Response

{
  "code": "01-300",
  "createdAt": "2021-03-24 17:26:46.983Z",
  "defaultLocationId": "cl478y6gc44873i4x52s5w1tu",
  "defaultTaxCodeId": "cl478y6j045973i4xd4yx5ads",
  "id": "ckmnpybisiy5x08abky4g2d1f",
  "name": "Salesforce Tower 32nd Floor",
  "startDate": null,
  "state": "OPEN",
  "updatedAt": "2021-03-24 17:26:46.983Z"
}

DELETE `/jobs/:idOrCode/locations`

Remove a location from a specific job. If the deleted location is the default location for the job, the default location will be automatically set to a different location on the job.

Parameters

Name	Type	Description	Example
locationId	`ID`	The ID of the location to remove from the job	`"ckmnpybisiy5x08abky4g2d1f"`

Response

The updated Job object.

Example Request

DELETE https://api.kojo.tech/jobs/01-300/locations?locationId=ckmnpybisiy5x08abky4g2d1f

Example Response

{
  "code": "01-300",
  "createdAt": "2021-03-24 17:26:46.983Z",
  "defaultLocationId": "cl478y6gc44873i4x52s5w1tu",
  "defaultTaxCodeId": "cl478y6j045973i4xd4yx5ads",
  "id": "ckmnpybisiy5x08abky4g2d1f",
  "name": "Salesforce Tower 32nd Floor",
  "startDate": null,
  "state": "OPEN",
  "updatedAt": "2021-03-24 17:26:46.983Z"
}

GET `/jobs/:idOrCode/phases`

Read the phases associated with a job.

Parameters

See Phase pagination parameters.

Response

A list of Phase objects.

Example Request

GET https://api.kojo.tech/jobs/01-300/phases?limit=10

Example Response

[
  {
    "code": "L",
    "createdAt": "2021-03-24 17:26:46.983Z",
    "description": "Lighting",
    "id": "ckmnpybixiy5y0817spfhmj78",
    "updatedAt": "2021-03-24 17:26:46.983Z"
  }
]

POST `/jobs/:idOrCode/phases`

Creates a job phase. Exactly the same as POST /job-phases except that the jobCode or jobId parameter is taken from the URL.

GET `/jobs/:jobIdOrCode/phases/:idOrCode`

Gets a single job phase. Exactly the same as GET /job-phases/:idOrCode except that the id, code, jobCode, and/or jobId parameters are taken from the URL as appropriate.

PATCH `/jobs/:jobIdOrCode/phases/:idOrCode`

Updates a job phase. Exactly the same as PATCH /job-phases/:idOrCode except that the id, code, jobCode, and/or jobId parameters are taken from the URL as appropriate.

GET `/jobs/:idOrCode/users`

Get users associated with a job.

Parameters

See User pagination parameters

Response

A list of User objects.

Example Request

GET https://api.kojo.tech/jobs/ckmnpybisiy5x08abky4g2d1f/users?limit=10

Example Response

[
  {
    "activated": true,
    "admin": false,
    "createdAt": "2021-03-24 17:26:46.983Z",
    "email": "foreman.bob@usekojo.com",
    "id": "ckmnpybixiy5y0817spfhmj78",
    "name": "Foreman Bob",
    "phone": "415-867-5309",
    "role": "Field",
    "updatedAt": "2021-03-24 17:26:46.983Z"
  }
]

POST `/jobs/:idOrCode/users`

Add a user to a specific job.

Parameters

Name	Type	Description	Example
userId	`ID`	The ID of the user to add to the job	`"ckmnpybisiy5x08abky4g2d1f"`

Response

The updated Job object.

Example Request

POST https://api.kojo.tech/jobs/01-300/users?userId=ckmnpybisiy5x08abky4g2d1f

Example Response

{
  "code": "01-300",
  "createdAt": "2021-03-24 17:26:46.983Z",
  "defaultLocationId": "cl478y6gc44873i4x52s5w1tu",
  "defaultTaxCodeId": "cl478y6j045973i4xd4yx5ads",
  "id": "ckmnpybisiy5x08abky4g2d1f",
  "name": "Salesforce Tower 32nd Floor",
  "startDate": null,
  "state": "OPEN",
  "updatedAt": "2021-03-24 17:26:46.983Z"
}

DELETE `/jobs/:idOrCode/users`

Remove a user from a specific job.

Parameters

Name	Type	Description	Example
userId	`ID`	The ID of the user to remove from the job	`"ckmnpybisiy5x08abky4g2d1f"`

Response

The updated Job object.

Example Request

DELETE https://api.kojo.tech/jobs/01-300/users?userId=ckmnpybisiy5x08abky4g2d1f

Example Response

{
  "code": "01-300",
  "createdAt": "2021-03-24 17:26:46.983Z",
  "defaultLocationId": "cl478y6gc44873i4x52s5w1tu",
  "defaultTaxCodeId": "cl478y6j045973i4xd4yx5ads",
  "id": "ckmnpybisiy5x08abky4g2d1f",
  "name": "Salesforce Tower 32nd Floor",
  "startDate": null,
  "state": "OPEN",
  "updatedAt": "2021-03-24 17:26:46.983Z"
}

GET `/jobs/:idOrCode/nextPurchaseOrderNumber`

Gets the next purchase order number that will be generated for that job.

Example Request

GET https://api.kojo.tech/jobs/01-300/nextPurchaseOrderNumber

Example Response

{
  "nextPurchaseOrderNumber": 12
}

POST `/jobs/:idOrCode/nextPurchaseOrderNumber`

Sets the next purchase order number to be used when a new purchase order is created. Example: If the current PO number for a job (123) is 100, setting nextCounter to 500 will result in the next Purchase Order to start counting from 500.

important

This feature needs to be enabled by customer support request.

caution

If the counter value is already in use, the system will keep incrementing by 1 until a free slot is found.

Parameters

Name	Type	Description	Example
nextCounter	`Integer`	The next purchase order number	`10`

Response

The updated Job object.

Example Request

POST https://api.kojo.tech/jobs/12412427/nextPurchaseOrderNumber
{
  "nextCounter": 25
}

Example Response

{
    "code": "12412427",
    "createdAt": "2023-12-01T00:47:19.148Z",
    "defaultLocationId": null,
    "defaultTaxCodeId": null,
    "id": "clplwnip7019r8ohueet287tv",
    "name": "SFMTA 3rd Street Rail",
    "startDate": null,
    "state": "OPEN",
    "updatedAt": "2023-12-01T00:47:19.148Z",
    "hasPhaseCodes": false,
    "nextPurchaseOrderCounter": 12
}

important

Schema​

Job​

Enums​

JobState​

REST Endpoints​

GET /jobs​

Parameters​

Response​

Example Request​

Example Response​

POST /jobs​

Parameters​

Response​

Example Request​

Example Response​

POST /jobs/batch​

warning

Parameters​

Upsert Jobs Input​

Response​

Example Request​

Example Response​

GET /jobs/:idOrCode​

Parameters​

Response​

Example Request​

Example Response​

PATCH /jobs/:idOrCode​

Parameters​

Response​

Example Request​

Example Response​

GET /jobs/:idOrCode/locations​

Parameters​

Response​

Example Request​

Example Response​

POST /jobs/:idOrCode/locations​

Parameters​

Response​

Example Request​

Example Response​

DELETE /jobs/:idOrCode/locations​

Parameters​

Response​

Example Request​

Example Response​

GET /jobs/:idOrCode/phases​

Parameters​

Response​

Example Request​

Example Response​

POST /jobs/:idOrCode/phases​

GET /jobs/:jobIdOrCode/phases/:idOrCode​

PATCH /jobs/:jobIdOrCode/phases/:idOrCode​

GET /jobs/:idOrCode/users​

Parameters​

Response​

Example Request​

Example Response​

POST /jobs/:idOrCode/users​

Parameters​

Response​

Example Request​

Example Response​

DELETE /jobs/:idOrCode/users​

Parameters​

Response​

Example Request​

Example Response​

GET /jobs/:idOrCode/nextPurchaseOrderNumber​

Example Request​

Example Response​

POST /jobs/:idOrCode/nextPurchaseOrderNumber​

important

caution

Parameters​

Response​

Example Request​

Schema

`Job`

Enums

`JobState`

REST Endpoints

GET `/jobs`

Parameters

Response

Example Request

Example Response

POST `/jobs`

Parameters

Response

Example Request

Example Response

POST `/jobs/batch`

Parameters

Upsert Jobs Input

Response

Example Request

Example Response

GET `/jobs/:idOrCode`

Parameters

Response

Example Request

Example Response

PATCH `/jobs/:idOrCode`

Parameters

Response

Example Request

Example Response

GET `/jobs/:idOrCode/locations`

Parameters

Response

Example Request

Example Response

POST `/jobs/:idOrCode/locations`

Parameters

Response

Example Request

Example Response

DELETE `/jobs/:idOrCode/locations`

Parameters

Response

Example Request

Example Response

GET `/jobs/:idOrCode/phases`

Parameters

Response

Example Request

Example Response

POST `/jobs/:idOrCode/phases`

GET `/jobs/:jobIdOrCode/phases/:idOrCode`

PATCH `/jobs/:jobIdOrCode/phases/:idOrCode`

GET `/jobs/:idOrCode/users`

Parameters

Response

Example Request

Example Response

POST `/jobs/:idOrCode/users`

Parameters

Response

Example Request

Example Response

DELETE `/jobs/:idOrCode/users`

Parameters

Response

Example Request

Example Response

GET `/jobs/:idOrCode/nextPurchaseOrderNumber`

Example Request

Example Response

POST `/jobs/:idOrCode/nextPurchaseOrderNumber`

Parameters

Response

Example Request

Example Response