> For the complete documentation index, see [llms.txt](https://docs.tiny.plus/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tiny.plus/api/endpoints/projects.md). # Projects Projects live at `/v2/projects`. They support every request on the [Records](/api/endpoints/records.md) page: list, get, history, create, update, delete and search. ## Status pipeline `GET` `https://api.tiny.plus/v2/status_history/projects/{{id}}` What a project's Status panel shows in tiny+: the states it has been in, where it is now and for how long, the state it would move to next, and the rest still to come. ```bash curl "https://api.tiny.plus/v2/status_history/projects/8814" \ -H "Authorization: Bearer {{user_access_token}}" ``` ```json { "id": "8814", "flavour": "projects", "past": [ {"value": "196", "status": "proposal", "phase_id": 196, "name": "Short Term", "colour": "#62c989", "days": 53, "entered": "2020-09-02T14:18:30Z", "left": "2020-10-26T02:36:45Z"}, {"value": "197", "status": "proposal", "phase_id": 197, "name": "Submission", "colour": "#62c989", "days": 0, "entered": "2020-10-26T02:36:45Z", "left": "2020-10-26T02:40:37Z"}, {"value": "won", "status": "won", "phase_id": null, "name": "Won!", "colour": "#1cb5e8", "days": 0, "entered": "2020-10-26T02:40:37Z", "left": "2020-10-26T06:03:23Z"} ], "current": {"value": "active", "status": "active", "phase_id": null, "name": "Active", "colour": "#2839ff", "days": 2166, "entered": "2020-10-26T06:03:23Z", "left": null}, "next": {"value": "completed", "status": "completed", "phase_id": null, "name": "Completed", "colour": "#aaaaaa", "days": null, "entered": null, "left": null}, "future": [ {"value": "62133", "status": "active", "phase_id": 62133, "name": "Act", "colour": "#2839ff", "days": null, "entered": null, "left": null} ] } ``` * A state is a phase, or a status with no phase set. `value` is what to send as `record_status` to move the project there, so `PATCH` with `next.value` moves it on. `name` is as the panel shows it. * `past` holds up to three states, in the pipeline's order rather than the order they happened in. A state visited more than once appears once: `days` is the total, `entered` its first entry and `left` its last exit. * `current.days` counts from when the project last entered its state. * An active project's `next` is completing it. A completed, lost or cancelled project has no `next` and no `future`. * Days are whole days and dates are in UTC. `use_cache=0` reads past the cache. | Case | Response | | ------------------------------------------------- | ------------------------------------------------------- | | Any type but projects | `404 {"error": "Only a project has a status history."}` | | No such project, or a deleted one | `404 {"error": "Record not found"}` | | A confidential project the token's user can't see | `403 {"error": "This record is confidential."}` | ## Creating a project ```bash curl -X POST "https://api.tiny.plus/v2/projects" \ -H "Authorization: Bearer {{user_access_token}}" \ -H "Content-Type: application/json" \ -d '{ "name": "New aged care facility, Auchenflower", "record_status": "proposal", "primary_company_id": "Auchenflower Aged Care", "assigned_user": "1231", "fee_value": "42000.00", "probability": "60" }' ``` ```javascript { "id": "161030" } ``` `name` is the only field a project needs. ## Finding projects The projects on a team member's team that changed since 1 September, newest first, with a few of their fields: ```bash curl "https://api.tiny.plus/v2/projects?staff=1231&modified_date=%3E2026-09-01&sort=modified_date%20desc&fields=id,name,record_status,fee_value,modified_date&return_format=array&with_related=0" \ -H "Authorization: Bearer {{user_access_token}}" ``` ```javascript { "total_records": 7, "returned_records": 7, "records": [ { "id": "62388", "name": "Example Project", "record_status": "proposal", "fee_value": "42000.00", "modified_date": "2026-09-17 21:28:27.0000000", "record_status_display": "Waiting", "show_obscured": false }, ... ] } ``` With `fields`, you get the fields you asked for, plus `record_status_display` and `show_obscured`. [Listing, filtering and paging](/api/concepts/listing.md) covers every filter. ## Status and phases A project's `record_status` is one of your account's project statuses, such as `proposal`, `won`, `active`, `completed`, `lost` or `cancelled`. `GET /v2/record_status/projects` lists them. If your account splits a status into phases, send a phase's id rather than the status. [Statuses and phases](/api/concepts/record-types.md#statuses-and-phases) explains how. ## The client company A project's client company is its `primary_company_id`. When you create or update a project, you can send either a company's id or its name. A name is matched exactly, and a new company is created if there's no match. See [Linking records](/api/concepts/linking.md#linking-a-client-company). ## Fee and value `fee_value` and `project_value` are amounts in whole units: cents are dropped, so `1234.56` is stored as `1234`. Send a plain number, or one written the way people type it, such as `$42k` or `1,500,000`. They come back as strings with two decimal places, and zero can come back as `".00"`. On accounts that use more than one currency, send the amount's currency in `fee_value_currency` or `project_value_currency`, such as `USD`. tiny+ converts the amount into the account's own currency at the account's exchange rate, and `fee_value_entered` keeps the fee as you sent it. `fee_value_weighted` is worked out for you: the fee multiplied by `probability`, divided by 100. ## Project and opportunity numbers `project_number` is your number for a project. If your account requires project numbers to be unique, creating a project with a number that's already used fails with a `400`, and an update to one is ignored. If your account numbers opportunities automatically, send `opportunity_number` as `Generate` to give a project the next number. ## Stages On accounts that split projects into stages, each stage is a record of its own, at `/v2/stages`. {% hint style="warning" %} On these accounts, `GET /v2/projects` lists one row per stage. * A row's `id` is the stage's id. `stage_id` and `stage_name` identify the stage, and `project_id` is the project's id. * The row's status, fee, probability, assigned user and dates are the stage's. * `total_records` counts rows, not projects. * A project without stages has one row, with `stage_id` set to `null` and `project_id` equal to its `id`. {% endhint %} * To get a project itself, use `GET /v2/projects/{{project_id}}`. A stage's id answers `404` there; read a stage with `GET /v2/stages/{{id}}`. * To list a project's stages, use `GET /v2/stages?primary_related={{project_id}}`. * To add a stage, `POST /v2/stages` with its `name` and `primary_related`, the project's id. Adding a stage marks its project as having stages, and adds the stage's assigned team member to the project's team. A stage's status can move its project from `proposal` to `won` or `active`. On accounts where a project's fee is the total of its stages' fees, changing a stage's fee updates the project's fee. ### Stage fields | Field | Label in tiny+ | Type | Notes | Editable | | ---------------------------- | ---------------------- | ---------- | ----------------------------------------------------- | -------- | | `name` | Stage Name | Text | Required. Up to 200 characters. | Yes | | `primary_related` | Project | Record id | Required. The id of the project the stage belongs to. | Yes | | `record_status` | Status | Option | Required. One of the project statuses. | Yes | | `stage_close_date` | Close Date | Date-time | In UTC. | Yes | | `stage_expected_duration` | Duration | Duration | An ISO 8601 duration, such as `P4M`. | Yes | | `stage_expected_finish_date` | Expected Finish Date | Date | `YYYY-MM-DD`. | Yes | | `stage_expected_start_date` | Expected Start Date | Date | `YYYY-MM-DD`. | Yes | | `stage_fee_value` | Fee Value | Amount | In whole units: cents are dropped. | Yes | | `stage_probability` | Probability of Success | Percentage | The chance of winning the stage, from 0 to 100. | Yes | ## Fields | Field | Label in tiny+ | Type | Notes | Editable | | --------------------------------- | ------------------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `assigned_user` | Assigned To | Team member id | A team member's id. | Yes | | `awards` | Awards and Recognition | Text | | Yes | | `close_date` | Close Date | Date-time | In UTC. When the project was won, lost or cancelled. | Yes | | `completed_date` | Completed Date | Date-time | In UTC. When the project was completed. | Yes | | `end_date` | Conclusion Date | Date | `YYYY-MM-DD`. | Yes | | `entered_status_or_phase_date` | Date Entered This Status | Date | When the project entered its current status or phase. | No | | `expected_duration` | Duration | Duration | An ISO 8601 duration, such as `P4M` for four months or `P14D` for 14 days. A value that isn't one is dropped. | Yes | | `expected_finish_date` | Expected Finish Date | Date | `YYYY-MM-DD`. | Yes | | `expected_start_date` | Expected Start Date | Date | `YYYY-MM-DD`. | Yes | | `extra_notes` | Extra Notes | Text | | Yes | | `fee_value` | Project Fee | Amount | In whole units: cents are dropped. See [Fee and value](#fee-and-value). Reads also return `fee_value_entered`, the fee as you sent it. | Yes | | `fee_value_currency` | Fee Value Currency | Currency code | The fee's currency, on accounts that use more than one. | Yes | | `fee_value_weighted` | Project Fee (Weighted) | Amount | The fee multiplied by `probability`, divided by 100. | No | | `final_record_phase_before_close` | Final Phase | Record id | The phase the project was in when it closed. | No | | `folder_location` | Project Folder | URL | A folder for the project, for example on a network drive. | Yes | | `has_stages` | Has Subprojects? | Yes/no | `1` if the project is split into stages. | No | | `health_rating` | Health | Health | The project's health, from 0 to 100. tiny+ works it out daily. | No | | `is_won` | Won? | Yes/no | `1` if the project has been won. | No | | `marketing_doc` | Marketing Document | Record id | The id of the project's marketing document. | Yes | | `name` | Project Name | Text | Required. The project's name. Up to 200 characters. | Yes | | `opportunity_number` | Opportunity Number | Text | Send `Generate` to give the project the next number, if your account numbers opportunities. | Yes | | `photographer` | Photographer Details | Text | | Yes | | `primary_company_id` | Client Company | Record id | The client company's id. You can send a company's name instead: see [Linking records](/api/concepts/linking.md#linking-a-client-company). | Yes | | `primary_contact` | Primary Contact | Record id | The primary contact's id. | Yes | | `probability` | Probability of Success | Percentage | The chance of winning the project, from 0 to 100. | Yes | | `project_address` | Project Address | Address | The project's address. Send it in parts: see [Addresses](/api/endpoints/companies.md#addresses). Reads return `project_address_address1` to `project_address_country`, and `project_address_geo_lat` and `project_address_geo_lng`. | Yes | | `project_number` | Project Number | Text | Your number for the project. See [Project and opportunity numbers](#project-and-opportunity-numbers). | Yes | | `project_value` | Project Value | Amount | In whole units: cents are dropped. See [Fee and value](#fee-and-value). | Yes | | `project_value_currency` | Project Value Currency | Currency code | The value's currency, on accounts that use more than one. | Yes | | `proposal_due_date` | Proposal Due | Date | `YYYY-MM-DD`. | Yes | | `proposal_received_date` | Proposal Received | Date | `YYYY-MM-DD`. | Yes | | `reason` | Feedback | Text | | Yes | | `record_status` | Project Status | Option | The project's status, or a phase id: see [Statuses and phases](/api/concepts/record-types.md#statuses-and-phases). | Yes | | `referee` | Referee | Text | | Yes | | `services_list` | Services Provided | Text | | Yes | | `stages_count` | Is A Subproject? | Yes/no | `1` if the project is a stage of another project. | No | | `start_date` | Commencement Date | Date | `YYYY-MM-DD`. | Yes | | `testimonial` | Client Testimonial | Text | | Yes | | `website_link` | Website Link | URL | | Yes | | `year_start` | Year Started | Whole number | A year, such as `2019`. Up to 4 characters. | Yes |