Outlign

Outlign API

v1.0 Documentation

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.

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.

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/external phases
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"
}

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: Phases cannot be created in template projects via the API. The API will return a 422 error if you attempt to create phases in template projects.

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