# 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 |