Phases API

Manage phases within projects. Phases help organize projects into logical stages or milestones, each containing related tasks and deliverables.

The Phase Object

{
  "id": 456,
  "title": "Design Phase",
  "due_date": "2023-03-15T23:59:59.000000Z",
  "is_internal": false,
  "order": 1,
  "project": { "id": 789, "title": "Website Redesign" },
  "client": { "id": 101, "title": "Acme Corporation" },
  "company": { "id": 202, "title": "Design Studio Inc" },
  "created_at": "2023-01-01T12:00:00.000000Z",
  "updated_at": "2023-01-01T12:00:00.000000Z"
}

due_date is returned as an empty string ("") when the phase has no due date. colour can be set when creating or updating a phase but is not returned in the phase object.

A phase's is_internal sets the audience for every task inside it. Tasks do not carry their own visibility — a task is internal (team-only) or client-facing according to the phase it belongs to. Moving a task to a phase on the other side is what changes its audience.

Attributes

Attribute	Type	Description
id	integer	Unique identifier for the phase
title	string	The phase's name
is_internal	boolean	Whether this phase is internal (not visible to clients)
due_date	string	Phase due date (ISO 8601), or `""` when not set
order	integer	Order of the phase within its project
project	object	The project this phase belongs to (`id`, `title`)
client	object	The client this phase belongs to (`id`, `title`)
company	object	The agency company that owns the phase (`id`, `title`)

List Phases

Retrieves a list of phases the authenticated user has access to. Phases belonging to template projects are always excluded.

GET /api/v1/phases

Query Parameters

Parameter	Type	Description
project_id	integer	Filter phases by specific project ID
client_id	integer	Filter phases by specific client ID
company_id	integer	Filter phases by specific company ID
is_internal	boolean	Filter by internal (`true`/`1`) or client-facing (`false`/`0`) phases. Pass `all` or an empty value to skip the filter
section_type	string	Filter by "client" (external) or "internal" phases
per_page	integer	Number of results per page (max 1000)

Example Request

GET /api/v1/phases?project_id=789§ion_type=client&per_page=25
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Note: Unlike other list endpoints, GET /api/v1/phases returns a plain array of phases (it is not wrapped in data and does not include pagination links/meta).

Example Response

[
  {
    "id": 456,
    "title": "Design Phase",
    "due_date": "2023-03-15T23:59:59.000000Z",
    "is_internal": false,
    "order": 1,
    "project": { "id": 789, "title": "Website Redesign" },
    "client": { "id": 101, "title": "Acme Corporation" },
    "company": { "id": 202, "title": "Design Studio Inc" },
    "created_at": "2023-01-01T12:00:00.000000Z",
    "updated_at": "2023-01-01T12:00:00.000000Z"
  }
]

Get a Phase

Retrieves a specific phase by ID.

GET /api/v1/phases/{id}

Example Request

GET /api/v1/phases/456
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Example Response

{
  "id": 456,
  "title": "Design Phase",
  "due_date": "2023-03-15T23:59:59.000000Z",
  "is_internal": false,
  "order": 1,
  "project": { "id": 789, "title": "Website Redesign" },
  "client": { "id": 101, "title": "Acme Corporation" },
  "company": { "id": 202, "title": "Design Studio Inc" },
  "created_at": "2023-01-01T12:00:00.000000Z",
  "updated_at": "2023-01-01T12:00:00.000000Z"
}

Create a Phase

Creates a new phase within a project.

POST /api/v1/phases

Request Body

Parameter	Type	Required	Description
title	string	Yes	The phase's name (max 255 chars)
project_id	integer	Yes	ID of the project this phase belongs to
is_internal	boolean	No	Whether this phase is internal (defaults to false)
due_date	string	No	Phase due date (YYYY-MM-DD HH:MM:SS format)
colour	string	No	Hex color code (max 7 chars, e.g., "#9177FB")

Example Request

POST /api/v1/phases
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json

{
  "title": "Development Phase",
  "project_id": 789,
  "is_internal": false,
  "due_date": "2023-04-30 23:59:59",
  "colour": "#659DE5"
}

Example Response

{
  "id": 457,
  "title": "Development Phase",
  "due_date": "2023-04-30T23:59:59.000000Z",
  "is_internal": false,
  "order": 2,
  "project": { "id": 789, "title": "Website Redesign" },
  "client": { "id": 101, "title": "Acme Corporation" },
  "company": { "id": 202, "title": "Design Studio Inc" },
  "created_at": "2023-01-15T10:00:00.000000Z",
  "updated_at": "2023-01-15T10:00:00.000000Z"
}

Update a Phase

Updates an existing phase. All fields are optional — only the fields you send are changed.

PUT PATCH /api/v1/phases/{id}

Request Body

Parameter	Type	Description
title	string	The phase's name (max 255 chars)
is_internal	boolean	Whether this phase is internal
due_date	string\|null	Phase due date (YYYY-MM-DD HH:MM:SS). Common date formats are accepted and normalised.
colour	string	Hex color code (max 7 chars, e.g., "#9177FB")
order	integer	Position of the phase within its project (min 0)

Example Request

PATCH /api/v1/phases/457
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json

{
  "title": "Development Phase (Sprint 2)",
  "due_date": "2023-05-15 23:59:59"
}

Reorder a Phase

Repositions a phase within its project. Phases move within their own side only — internal phases among internal phases, client-facing among client-facing — since the two sides render as separate boards. Pass either position ("first" or "last") or after_phase_id to place the phase directly after another phase on the same side.

POST /api/v1/phases/{id}/reorder

Parameters

Parameter	Type	Description
position	string	`"first"` or `"last"`. Required unless `after_phase_id` is given.
after_phase_id	integer	Place the phase directly after this phase. Must belong to the same project and side; returns `422` otherwise.

Example Request

POST /api/v1/phases/457/reorder
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "after_phase_id": 456
}

Returns the updated phase object, including its new order.

Delete a Phase

Permanently deletes a phase along with its tasks. This cannot be undone.

DELETE /api/v1/phases/{id}

Example Request

DELETE /api/v1/phases/457
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Example Response

204 No Content

Phase Types

Phases can be either client-facing or internal, allowing you to organize work visibility.

Client Phases

• is_internal: false
• Visible to clients
• Used for external deliverables
• Default phase type

Internal Phases

• is_internal: true
• Hidden from clients
• Used for internal processes
• Team planning and coordination

Important Notes

Template Projects: Templates are edited inside Outlign, not through this API. Phases of template projects are excluded from GET /api/v1/phases, and POST /api/v1/phases returns a 422 error ("Cannot create phases in template projects") if project_id refers to a template.

Phase Ordering: New phases are automatically assigned the next order number within their project. Phases are returned in order when listing.

Outlign API

Phases API

The Phase Object

Attributes

List Phases

Query Parameters

Example Request

Example Response

Get a Phase

Example Request

Example Response

Create a Phase

Request Body

Example Request

Example Response

Update a Phase

Request Body

Example Request

Reorder a Phase

Parameters

Example Request

Delete a Phase

Example Request

Example Response

Phase Types

Client Phases

Internal Phases

Important Notes