Phases

Phases in Kojo are the work breakdown/activity structure your company has defined. Currently Kojo does not support a nested phase structure (i.e. sub-phases), so external systems should flatten their phase structure if they wish to appopriately code them into Kojo. Depending on how you company chooses to implement them, phases can be defined at a global level or at a per-job level. Global phases do not have an associated job.

tip

Common phases seen in Kojo may include things like; "Rough-In", "Finishing", "Lighting", etc. It is best practice where feasable to standardize phases in order to conduct Job-to-Job analysis on phase estimation accuracy.

Schema

Phase

Name	Type	Description	Example
id	ID	The unique phase ID	"ckmnpybisiy5x08abky4g2d1f"
createdAt	DateTime	When this phase was created	"2021-03-24 17:26:46.983Z"
code	string	The human-readable code to identify this phase	"L"
description	string	A description of this phase	"Lighting"
job.code	string	The code of the job this phase is linked to	"01-300"
job.id	ID	The ID of the job this phase is linked to	"ckmnpybisiy5x08abky4g2d1f"
updatedAt	DateTime	When this phase was last modified	"2021-03-24 17:26:46.983Z"
defaultGLCode	string?	Optional. The default GL code for this phase	"123456"

REST Endpoints (Global Phases)

GET /global-phases

Read all global phases.

Parameters

Accepts all standard pagination parameters.

Allowed orderBy fields: code, createdAt, description, id, updatedAt.

Allowed filter fields: code, createdAt, description, id, updatedAt.

Response

A list of Phase objects.

Example Request

GET https://api.kojo.tech/global-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 /global-phases

Creates a global phase.

Parameters

Name	Type	Description	Example
code	string	A unique human-readable code to represent this phase	"L"
description	string	A description of the phase	"Lighting"

Response

The created Phase object.

Example Request

POST https://api.kojo.tech/global-phases
{
  "code": "L",
  "description": "Lighting",
}

Example Response

{
    "code": "L",
    "createdAt": "2021-04-17T00:23:37.226Z",
    "description": "Lighting",
    "id": "cknkzyyve051p07338go86qy5",
    "updatedAt": "2021-04-17T00:23:37.226Z",
}

POST /global-phases/batch

Creates or Updates multiple phases at once.

warning

Batch endpoints will accept at most 1000 elements per request.

Parameters

Name	Type	Description	Example
inputs	UpsertInput[]	A list of upsert inputs

Upsert Input

Name	Type	Description	Example
code	string	A unique human-readable code to represent this phase	"01-300"
description	string	A description of the phase	"Salesforce Tower 32nd Floor"
jobCode	string?	The job this phase will be linked to	"01-300"
jobId	ID?	The job this phase will be linked to	"ckmnpybisiy5x08abky4g2d1f"
defaultGLCode	string?	Optional. The default GL code for this phase	"123456"

note

If you pass jobId or jobCode properties the phase will not be created as Global.

Response

A list of Phases.

Example Request

POST https://api.kojo.tech/global-phases/batch
{
  "inputs": [
    {
      code: "01-200",
      description: "Rough-in",
      jobId: "ckmnpybisiy5x08abky4g2d1f"
    }
  ]
}

Example Response

[
  {
    "id": "ckds5x1invtwj0804ftyg185b",
    "description": "Rough-in",
    "jobId": "ckmnpybisiy5x08abky4g2d1f"
  }
]

GET /global-phases/:idOrCode

Get a single Phase. A phase ID or phase code must be specified

Parameters

Name	Type	Description	Example
code	string	A unique human-readable code to represent this phase	"01-300"
id	ID	The phase ID	"ckmnpybisiy5x08abky4g2d1f"

Response

The requested Phase.

Example Request

GET https://api.kojo.tech/global-phases/L?jobCode=01-200

Example Response

{
    "code": "L",
    "createdAt": "2021-04-17T00:23:37.226Z",
    "description": "Lighting",
    "id": "ckmnpybisiy5x08abky4g2d1f",
    "updatedAt": "2021-04-17T00:23:37.226Z",
}

PATCH /global-phases/:idOrCode

Updates a phase. A phase ID or phase code must be specified.

Parameters

Name	Type	Description	Example
code	string	A unique human-readable code to represent this phase	"01-300"
description	string	A description of the phase	"Salesforce Tower 32nd Floor"
id	ID	The phase ID	"ckmnpybisiy5x08abky4g2d1f"

Response

The updated Phase.

Example Request

PATCH https://api.kojo.tech/global-phases/ckmnpybisiy5x08abky4g2d1f
{
  "description": "Lighting edited"
}

Example Response

{
    "code": "L",
    "createdAt": "2021-04-17T00:23:37.226Z",
    "description": "Lighting edited",
    "id": "ckmnpybisiy5x08abky4g2d1f",
    "updatedAt": "2021-04-17T00:23:37.226Z",
}

DELETE /global-phases/:id

Delete a phase. A phase ID code must be specified.

Response

The deleted Phase.

Example Request

DELETE https://api.kojo.tech/global-phases/ckmnpybisiy5x08abky4g2d1f

Example Response

{
    "code": "L",
    "createdAt": "2021-04-17T00:23:37.226Z",
    "description": "Lighting edited",
    "id": "ckmnpybisiy5x08abky4g2d1f",
    "updatedAt": "2021-04-17T00:23:37.226Z",
    "deletedAt": "2021-04-17T00:23:37.226Z",
}

REST Endpoints (Job Phases)

Endpoints for job-related phases. We've provided top-level endpoints to query for all phases associated with jobs across the org, as well as job-specific phase endpoints.

GET /job-phases

Read all phases related to jobs.

Parameters

Accepts all standard pagination parameters.

Allowed orderBy fields: code, createdAt, description, id, updatedAt

Response

A list of Phase objects.

Example Request

GET https://api.kojo.tech/job-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"
  }
]

GET /jobs/:jobIdOrCode/phases

Read all phases related to the provided job.

Parameters

Name	Type	Description	Example
jobCode	string	Only request phases for this job	"01-300"
jobId	ID	Only request phases for this job	"ckmnpybisiy5x08abky4g2d1f"

Accepts all standard pagination parameters.

Allowed orderBy fields: code, createdAt, description, id, updatedAt

Response

A list of Phase objects.

Example Request

GET https://api.kojo.tech/jobs/:ckmnpybisiy5x08abky4g2d1f/phases

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/:jobIdOrCode/phases

Creates a phase. You must specify either a jobCode or jobId in the URL.

Parameters

Name	Type	Description	Example
code	string	A unique human-readable code to represent this phase	"L"
description	string	A description of the phase	"Lighting"
jobCode	string	The job this phase will be linked to	"01-300"
jobId	ID	The job this phase will be linked to	"ckmnpybisiy5x08abky4g2d1f"
defaultGLCode	string?	Optional. The default GL code for this phase	"123456"

Response

The created Phase object.

Example Request

POST https://api.kojo.tech/jobs/:ckmnpybisiy5x08abky4g2d1f/phases
{
  "code": "L",
  "description": "Lighting",
  "jobCode": "01-100"
}

Example Response

{
    "code": "L",
    "createdAt": "2021-04-17T00:23:37.226Z",
    "description": "Lighting",
    "id": "cknkzyyve051p07338go86qy5",
    "updatedAt": "2021-04-17T00:23:37.226Z",
    "jobCode": "01-100",
    "jobId": "ckmvlpvv4001e073355gknfs6"
}

GET /jobs/:jobIdOrCode/phases/:phaseIdOrCode

Get a single job-related. A phase ID must be specified, OR a job code/ID and job phase code.

Parameters

Name	Type	Description	Example
code	string	A unique human-readable code to represent this phase	"01-300"
jobCode	string	The code of the job this phase is linked to	"01-300"
jobId	ID	The ID of the job this phase is linked to	"ckmnpybisiy5x08abky4g2d1f"
id	ID	The phase ID	"asdfybisiy5x08abky4g52fah"

Response

The requested Phase.

Example Request

GET https://api.kojo.tech/jobs/ckmnpybisiy5x08abky4g2d1f/phases/asdfybisiy5x08abky4g52fah

Example Response

{
    "code": "L",
    "createdAt": "2021-04-17T00:23:37.226Z",
    "description": "Lighting",
    "id": "asdfybisiy5x08abky4g52fah",
    "updatedAt": "2021-04-17T00:23:37.226Z",
    "jobCode": "01-200",
    "jobId": "ckmnpybisiy5x08abky4g2d1f",
    "defaultGLCode": null
}

PATCH /jobs/:jobIdOrCode/phases/:phaseIdOrCode

Updates a phase. A phase ID must be specified, as well as a job code/ID and phase code.

Parameters

Name	Type	Description	Example
code	string	A unique human-readable code to represent this phase	"01-300"
description	string	A description of the phase	"Salesforce Tower 32nd Floor"
jobCode	string	The code of the job this phase is linked to	"01-300"
jobId	ID	The ID of the job this phase is linked to	"ckmnpybisiy5x08abky4g2d1f"
id	ID	The phase ID	"asdfybisiy5x08abky4g52fah"
defaultGLCode	string?	Optional. The default GL code for this phase	"123456"

Response

The updated Phase.

Example Request

PATCH https://api.kojo.tech/jobs/asdfybisiy5x08abky4g52fah/phases/asdfybisiy5x08abky4g52fah
{
  "description": "Lighting edited"
}

Example Response

{
    "code": "L",
    "createdAt": "2021-04-17T00:23:37.226Z",
    "description": "Lighting edited",
    "id": "asdfybisiy5x08abky4g52fah",
    "updatedAt": "2021-04-17T00:23:37.226Z",
    "jobCode": "01-200",
    "jobId": "asdfybisiy5x08abky4g52fah",
    "defaultGLCode": null
}

DELETE /jobs/:jobIdOrCode/phases/:phaseIdOrCode

Delete a phase. A phase ID code must be specified.

Response

The deleted Phase.

Example Request

DELETE https://api.kojo.tech/global-phases/ckmnpybisiy5x08abky4g2d1f

Example Response

{
    "code": "L",
    "createdAt": "2021-04-17T00:23:37.226Z",
    "description": "Lighting edited",
    "id": "asdfybisiy5x08abky4g52fah",
    "updatedAt": "2021-04-17T00:23:37.226Z",
    "deletedAt": "2021-04-17T00:23:37.226Z",
    "jobCode": "01-200",
    "jobId": "asdfybisiy5x08abky4g52fah",
    "defaultGLCode": null
}