Projects API

Projects represent scoped work for a company. They can be billed as time & materials, fixed fee, or against a retainer agreement.

The Project Object

{
  "id": "prj_cuid123456",
  "title": "Website Redesign",
  "description": "Complete redesign of corporate website with new CMS",
  "client_id": "cli_xxxxx",
  "status": "active",
  "type_id": "ptype_xxxxx",
  "billing_type": "fixed_fee",
  "manager_id": "usr_xxxxx",
  "contact_id": "con_xxxxx",
  "agreement_id": null,
  "dates": {
    "start_date": "2026-01-15",
    "due_date": "2026-03-31",
    "commenced_at": "2026-01-16T09:00:00Z",
    "completed_at": null
  },
  "budget": {
    "hours": 200.00,
    "amount": 25000.00,
    "hours_used": 87.50,
    "amount_billed": 10937.50,
    "percent_complete": 43.75
  },
  "rate": {
    "override": false,
    "rate_id": null,
    "custom_rate": null
  },
  "notes": "Priority project - CEO visibility",
  "contract_url": "https://drive.google.com/...",
  "created_at": "2026-01-10T14:30:00Z",
  "updated_at": "2026-01-22T11:15:00Z"
}

Project Fields

Field	Type	Description
`id`	string	Unique identifier (prefix: `prj_`)
`title`	string	Required. Project name
`description`	string	Project description
`client_id`	string	Required. Associated client
`status`	enum	Project status (see below)
`type_id`	string	Project type category
`billing_type`	enum	How this project is billed
`manager_id`	string	Assigned project manager
`contact_id`	string	Primary client contact
`agreement_id`	string	Retainer agreement (if billing type is `retainer`)
`dates`	object	Project dates
`budget`	object	Budget and progress tracking
`rate`	object	Rate overrides
`notes`	string	Internal notes
`contract_url`	string	Link to contract/SOW document
`created_at`	datetime	When the project was created
`updated_at`	datetime	When the project was last updated

Project Status

Status	Description
`pending`	Not started, planning phase
`active`	Work in progress
`on_hold`	Paused (client decision, blocker, etc.)
`completed`	All work finished
`cancelled`	Project cancelled

Billing Types

Type	Description
`time_and_materials`	Bill actual hours at rate
`fixed_fee`	Fixed price with milestone billing
`retainer`	Bill against retainer agreement
`non_billable`	Internal or pro-bono work

List Projects

GET/v1/projectsList all projects

Returns a paginated list of projects.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	20	Results per page (max: 100)
`client_id`	string		Filter by client
`status`	string		Filter by status
`billing_type`	string		Filter by billing type
`manager_id`	string		Filter by project manager
`type_id`	string		Filter by project type
`search`	string		Search project titles
`sort`	string	`created_at`	Sort by: `title`, `created_at`, `due_date`, `status`
`order`	string	`desc`	Sort order: `asc`, `desc`

Request

curl "https://api.govantage.co/v1/projects?status=active&manager_id=usr_xxxxx" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Response

{
  "data": [
    {
      "id": "prj_cuid123456",
      "title": "Website Redesign",
      "client_id": "cli_xxxxx",
      "client_name": "Acme Corporation",
      "status": "active",
      "billing_type": "fixed_fee",
      "manager_id": "usr_xxxxx",
      "dates": {
        "due_date": "2026-03-31"
      },
      "budget": {
        "hours": 200.00,
        "hours_used": 87.50,
        "percent_complete": 43.75
      },
      "created_at": "2026-01-10T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 45,
    "total_pages": 3
  }
}

Create a Project

POST/v1/projectsCreate a new project

Request Body

Field	Type	Required	Description
`title`	string	Yes	Project name
`client_id`	string	Yes	Client ID
`description`	string	No	Project description
`status`	string	No	Default: `pending`
`type_id`	string	No	Project type ID
`billing_type`	string	No	Default: `time_and_materials`
`manager_id`	string	No	Project manager user ID
`contact_id`	string	No	Client contact ID
`agreement_id`	string	No	Retainer agreement ID
`start_date`	date	No	Project start date
`due_date`	date	No	Target completion date
`budget_hours`	decimal	No	Budgeted hours
`budget_amount`	decimal	No	Budget amount (for fixed fee)
`notes`	string	No	Internal notes
`contract_url`	string	No	Link to contract document

Request

curl -X POST "https://api.govantage.co/v1/projects" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Website Redesign",
    "client_id": "cli_xxxxx",
    "description": "Complete redesign of corporate website",
    "billing_type": "fixed_fee",
    "manager_id": "usr_xxxxx",
    "start_date": "2026-02-01",
    "due_date": "2026-04-30",
    "budget_hours": 200,
    "budget_amount": 25000
  }'

Response

{
  "data": {
    "id": "prj_cuid789012",
    "title": "Website Redesign",
    "client_id": "cli_xxxxx",
    "description": "Complete redesign of corporate website",
    "status": "pending",
    "billing_type": "fixed_fee",
    "manager_id": "usr_xxxxx",
    "dates": {
      "start_date": "2026-02-01",
      "due_date": "2026-04-30"
    },
    "budget": {
      "hours": 200.00,
      "amount": 25000.00,
      "hours_used": 0,
      "amount_billed": 0,
      "percent_complete": 0
    },
    "created_at": "2026-01-25T10:30:00Z",
    "updated_at": "2026-01-25T10:30:00Z"
  }
}

Get a Project

GET/v1/projects/:idRetrieve a project by ID

Path Parameters

Parameter	Description
`id`	The project ID

Query Parameters

Parameter	Type	Description
`include`	string	Comma-separated: `client`, `manager`, `tickets`, `time_entries`, `milestones`, `phases`, `tasks`

Request

curl "https://api.govantage.co/v1/projects/prj_cuid123456?include=tickets,time_entries" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Response

{
  "data": {
    "id": "prj_cuid123456",
    "title": "Website Redesign",
    "client_id": "cli_xxxxx",
    "description": "Complete redesign of corporate website with new CMS",
    "status": "active",
    "billing_type": "fixed_fee",
    "manager_id": "usr_xxxxx",
    "dates": {
      "start_date": "2026-01-15",
      "due_date": "2026-03-31",
      "commenced_at": "2026-01-16T09:00:00Z"
    },
    "budget": {
      "hours": 200.00,
      "amount": 25000.00,
      "hours_used": 87.50,
      "amount_billed": 10937.50,
      "percent_complete": 43.75
    },
    "tickets": [
      {
        "id": "tkt_xxxxx",
        "title": "Homepage wireframes",
        "status": "completed"
      },
      {
        "id": "tkt_yyyyy",
        "title": "Design system setup",
        "status": "in_progress"
      }
    ],
    "time_entries": {
      "total_hours": 87.50,
      "billable_hours": 85.00,
      "by_user": [
        { "user_id": "usr_xxxxx", "hours": 45.00 },
        { "user_id": "usr_yyyyy", "hours": 42.50 }
      ]
    },
    "created_at": "2026-01-10T14:30:00Z",
    "updated_at": "2026-01-22T11:15:00Z"
  }
}

Update a Project

PUT/v1/projects/:idUpdate a project

Path Parameters

Parameter	Description
`id`	The project ID

Request

curl -X PUT "https://api.govantage.co/v1/projects/prj_cuid123456" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "due_date": "2026-04-15",
    "notes": "Extended deadline per client request"
  }'

Delete a Project

DELETE/v1/projects/:idDelete a project

Deleting a project removes all associated tickets, time entries, and tasks. This action cannot be undone. Consider setting status to cancelled instead.

Request

curl -X DELETE "https://api.govantage.co/v1/projects/prj_cuid123456" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Project Tickets

List Project Tickets

GET/v1/projects/:id/ticketsList tickets for a project

curl "https://api.govantage.co/v1/projects/prj_cuid123456/tickets" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Create Project Ticket

POST/v1/projects/:id/ticketsCreate a ticket under this project

curl -X POST "https://api.govantage.co/v1/projects/prj_cuid123456/tickets" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implement contact form",
    "description": "Add contact form to homepage with validation",
    "priority_id": "pri_xxxxx",
    "assignee_id": "usr_xxxxx"
  }'

Project Time Entries

List Project Time

GET/v1/projects/:id/time-entriesList time entries for a project

curl "https://api.govantage.co/v1/projects/prj_cuid123456/time-entries?from=2026-01-01&to=2026-01-31" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Project Milestones

List Milestones

GET/v1/projects/:id/milestonesList milestones for a project

Create Milestone

POST/v1/projects/:id/milestonesCreate a milestone

curl -X POST "https://api.govantage.co/v1/projects/prj_cuid123456/milestones" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Design Complete",
    "due_date": "2026-02-15",
    "amount": 5000,
    "description": "All design deliverables approved"
  }'

Project Phases

List Phases

GET/v1/projects/:id/phasesList phases for a project

Reorder Phases

PUT/v1/projects/:id/phases/reorderReorder project phases

curl -X PUT "https://api.govantage.co/v1/projects/prj_cuid123456/phases/reorder" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phase_ids": ["phase_1", "phase_3", "phase_2", "phase_4"]
  }'

Budget Tracking

Projects track budget consumption automatically:

Metric	Description
`hours_used`	Total hours logged against project
`amount_billed`	Total amount invoiced
`percent_complete`	Progress percentage

Budget alerts are triggered at 75%, 90%, and 100% consumption. Configure notification settings in the dashboard.

Webhooks

Subscribe to project events:

Event	Description
`project.created`	New project created
`project.updated`	Project details changed
`project.status_changed`	Status transitioned
`project.budget_alert`	Budget threshold crossed
`project.completed`	Project marked complete

Next Steps

Tickets API - Manage project tasks
Time Entries API - Log time to projects
Invoices API - Bill for project work