# Projects ## Get a Project `GET` `https://api.tiny.plus/v2/projects/{{id}}` This endpoint allows you to get a full Project record. #### Path Parameters | Name | Type | Description | | ---- | ------ | ----------------- | | id | number | ID of the project | #### Query Parameters | Name | Type | Description | | ------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | with\_related | boolean |

Can be either 1 or 0. Default is 1. When passed, information about the related records to the requested record are also returned, in a 'related' object.
If you don't need the related records, set this to 0 for a performance improvement.

| #### Headers | Name | Type | Description | | ------------- | ------ | ------------------ | | Authorization | string | Your access token. | {% tabs %} {% tab title="200 Project successfully retrieved." %} ```javascript { "id": 1233 "name": "RACF, Auchenflower", "record_status": "active", "description": "A new aged care facility.", "assigned_user": 1231, ... } ``` {% endtab %} {% tab title="404 Could not find a project matching the provided ID." %} ```javascript { "message": "Project not found." } ``` {% endtab %} {% endtabs %} #### Example Usage {% tabs %} {% tab title="jQuery" %} ```javascript var settings = { "url": "https://api.tiny.plus/v2/projects/{{id}}", "method": "GET", "headers": { "Authorization": "{{user_access_token}}" } }; $.ajax(settings).done(function (response) { console.log(response); }); ``` {% endtab %} {% tab title="PHP" %} ```php "https://api.tiny.plus/v2/projects/{{id}}", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => false, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => array( "Authorization: {{user_access_token}}" ), )); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; } ?> ``` {% endtab %} {% endtabs %} ## List Projects `GET` `https://api.tiny.plus/v2/projects` This endpoint allows you to get a paginated list of Projects, optionally filtered by criteria. #### Query Parameters | Name | Type | Description | | --------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | {{field\_name}} | string |

You can provide any {{field\_name}} listed in the Fields Reference as a filter to the projects returned.

You can also provide a minimum or maximum value by prepending a < or > before your value, which is useful for returning records modified or created after a certain datetime stamp.

To return all projects for user 1232:
/projects/?assigned\_user=1232

To return all projects modified after a date:
/projects/?modified\_date=>2019-01-01 14:00:00

To return all Active projects:
/projects/?record\_status=active

| | with\_health | boolean | If this key is present, we will return a `health` key for each returned record, which is a score between 0 and 100 identifying the relative health of that Project record. | | me | boolean | If this key is present, it will limit the results to only records where the user associated with the API key is the `assigned_user` or is in the Project Team. | | subscribed | boolean | Similar to the `me` parameter, this parameter when present returns all records for the user associated with the API key is the `assigned_user`, or is in the Project Team, *or is a subscriber to the record.* | | limit | number | Used for pagination. Limit is the number of records to return from the full resultset. The default is `15`. | | start | number | Used for pagination. Set this value to the cursor position into the total resultset to return this time. eg. to receive the 101st to the 115th record, set this to `100` and the limit parameter to `15`. Default is `0`. | | sort | string | Provide a field name and optionally a direction separated by a space to sort the returned results. For example, `modified_date desc` to return the most recently modified records. The two directions available are `asc` and `desc`. If you do not provide a direction `asc` is assumed. You can sort by any Number, Date or Text field in the **Fields Reference** below. | | return\_format | string |

Can be either array or object. The default is object.
When set to array, you will receive a simply array of records inside the 'records' key of the returned parent JSON object.

| | with\_related | boolean |

Can be either 1 or 0. Default is 1. When passed, related records to the main returned record are also returned, in a 'related' object.
If you don't need the related records, set this to 0 for a performance improvement.

| #### Headers | Name | Type | Description | | ------------- | ------ | ------------------ | | Authorization | string | Your access token. | {% tabs %} {% tab title="200 You will receive a JSON object containing all the relevant project fields." %} ``` { total_records: 125, returned_records: 50, records: [ { id: 1234, name: 'Example Project', ... }, { id: 1235, name: 'Second Example Project', ... } ] } ``` {% endtab %} {% endtabs %} #### Example Usage {% tabs %} {% tab title="jQuery" %} ```javascript var settings = { "url": "https://api.tiny.plus/v2/projects?me&return_format=array", "method": "GET", "headers": { "Authorization": "{{user_access_token}}" } }; $.ajax(settings).done(function (response) { console.log(response); }); ``` {% endtab %} {% tab title="PHP" %} ```php "https://api.tiny.plus/v2/projects?me&return_format=array", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => false, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => array( "Authorization: {{user_access_token}}" ), )); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; } ?> ``` {% endtab %} {% endtabs %} ## Create a Project `POST` `https://api.tiny.plus/v2/projects` You can create a new tiny+ project with this endpoint. The only required field to create a Project in tiny+ is `name`, however we recommend you provide as much information as possible. #### Headers | Name | Type | Description | | ------------- | ------ | ---------------------- | | Accepts | string | Use `application/json` | | Content-Type | string | Use `application/json` | | Authorization | string | Your access token. | #### Request Body | Name | Type | Description | | ----------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | JSON object | object |

{
"name": "New RACF, Auchenflower",
"record\_status": "proposal",
"assigned\_user": 27110
"description": "A new aged care facility"
....
}

| {% tabs %} {% tab title="200 A JSON object is returned with your new tiny+ record ID." %} ``` { id: [your new ID] } ``` {% endtab %} {% tab title="400 If there was a problem adding the record, you'll receive a 400 response." %} ``` { error: 'Error adding the record.' } ``` {% endtab %} {% tab title="403 If you do not have permission to add the record, you'll receive a 403 response." %} ``` ``` {% endtab %} {% endtabs %} ## Update a Project `PATCH` `https://api.tiny.plus/v2/projects/{{id}}` You can edit a tiny+ Project with this endpoint. In the request body, you only need to provide the fields that you would like to change. These can be provided as either a JSON object or in `application/x-www-form-urlencoded` format. #### Path Parameters | Name | Type | Description | | ---- | ------ | ------------------ | | id | number | ID of the project. | #### Headers | Name | Type | Description | | ------------- | ------ | ---------------------- | | Accepts | string | Use `application/json` | | Content-Type | string | Use `application/json` | | Authorization | string | Your access token. | #### Request Body | Name | Type | Description | | ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | JSON object | object |

{
"name": "New RACF, Auchenflower",
"record\_status": "proposal",
"assigned\_user": 27110,
"description": "A new aged care facility"
....
}

| {% tabs %} {% tab title="200 " %} ``` ``` {% endtab %} {% endtabs %} ## Delete a Project `DELETE` `https://api.tiny.plus/v2/projects/{{id}}` Delete a Project record. #### Path Parameters | Name | Type | Description | | ---- | ------ | ------------------ | | id | string | ID of the project. | #### Headers | Name | Type | Description | | ------------- | ------ | ------------------ | | Authorization | string | Your access token. | {% tabs %} {% tab title="200 " %} ``` ``` {% endtab %} {% tab title="400 " %} ``` ``` {% endtab %} {% endtabs %} ## Projects Field Reference | Field | Type | Details | Permission | | ---------------------- | :--------------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------: | | id | Number | Unique record identifier. | Read-only | | name |

String (up to 200 characters).

REQUIRED.

| Project Name. | Full | | description | String | Description. | Full | | created\_date | String (Y-m-d h:i:s) | Date record was first created. | Read-only | | modified\_date | String (Y-m-d h:i:s) | Date record was last modified. | Read-only | | created\_user | Number | ID of user who made the record. | Read-only | | modified\_user | Number | ID of user who last edited the record. | Read-only | | assigned\_user | Number | ID of assigned user. | Full | | is\_synced | Boolean | Whether the record has been synced from another source. | Full | | sync\_origin | String (up to 50 characters) | A simple string that you supply to let tiny+ users know where the record is synced from. | Full | | remote\_id | String (up to 200 characters) | A remote identifier for this record. | Full | | record\_status | String |

The status of the Project. Values you can use: proposal, won, active, completed, lost, cancelled.

When adding or editing a project, if your account is using additional phases for project status, you must pass the correct phase ID here in place of the possible values.

| Full | | record\_url | String | The fully qualified URI of the record. | Read-only | | project\_number | String | The user-friendly identifier for this project. | Full | | primary\_company\_id | String \| ID |

When reading this field, it will display the ID of the primary related company.

When adding or updating, you can provide EITHER an ID, or a string with the company name. If you provide a string, a company will be created with that name. If a company with that exact name already exists, it will be matched to that company.

| Full | | year\_start | Number | A YYYY date. eg. 2019 | Full | | project\_value | Currency |

The value of the project, to 2 decimal places. Do not include currency signs when adding or updating. eg provide

20000.00 for $20,000.

| Full | | fee\_value | Currency |

The fee value, to 2 decimal places. Do not include currency signs when adding or updating. eg provide

20000.00 for $20,000.

| Full | | folder\_location | String | A field to set a local or network folder location, for example to a network drive in a corporate network. | Full | | testimonial | String | A client testimonial provided by the user about this project. | Full | | website\_link | URL | An external URL that hosts information about this Project. | Full | | project\_address | String | A project's physical address. | Full | | close\_date | String (YYYY-MM-DD hh:mm:ss) | The datetime stamp that the project was marked as won, lost or cancelled. | Read-only | | expected\_start\_date | String (YYYY-MM-DD) | A user provided date for when the project is expected to commence. | Full | | expected\_duration | String (ISO 8601 Duration-only format) |

A user provided period identifying the expected length of time this project will run for.

(eg. P4M for 4 months, P14D for 2 weeks, P40D for 40 days)

| Full | | expected\_finish\_date | String (YYYY-MM-DD) | A user provided date for when the project is expected to conclude. | Full | | probability | Number (0-100) | The percentage chance the project will close. | Full | | completed\_date | String (YYYY-MM-DD hh:mm:ss) | The datetime stamp the project was marked as completed. | Read-only | | created\_date\_daysago | Number | How long since the project was created, in days. | Read-only | | start\_date | String (YYYY-MM-DD) | The recorded date the project began. | Full | | end\_date | String (YYYY-MM-DD) | The recorded date the project finished. | Full | | photographer | Text | The photographer used on the project. | Full | | awards | Text | The awards given to the project. | Full | | extra\_notes | Text | An extra notes field. | Full | | referee | Text | The project referee. | Full | | external\_url | String or JSON object |

A link to this project in another system. Helpful when used with sync\_origin. This can hold a simple string URL. However some records may exist in multiple systems, so we recommend you namespace your external URL by providing a JSON object like so:

{ "MyApp": "" }

This will make sure that other integrations will not interfere with your URL.

| Full | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tiny.plus/api/endpoints/projects.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.