# Companies ## Get a Company `GET` `https://api.tiny.plus/v2/companies/{{id}}` This endpoint allows you to get a full Company record. #### Path Parameters | Name | Type | Description | | ---- | ------ | ----------------- | | id | number | ID of the company | #### 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 Company successfully retrieved." %} ```javascript { "id": 1237 "name": "Auchenflower Aged Care", "record_status": "prospect", "description": "A large aged care provider based in Queensland, Australia.", "assigned_user": 1231, ... } ``` {% endtab %} {% tab title="404 Could not find a company matching the provided ID." %} ```javascript { "message": "Company not found." } ``` {% endtab %} {% endtabs %} #### Example Usage {% tabs %} {% tab title="jQuery" %} ```javascript var settings = { "url": "https://api.tiny.plus/v2/companies/{{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/companies/{{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 Companies `GET` `https://api.tiny.plus/v2/companies` This endpoint allows you to get a paginated list of Companies, 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 Company 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.
The default sort is name asc.

| | 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 company fields." %} ``` { total_records: 31, returned_records: 31, records: [ { id: 1237, name: 'Auchenflower Aged Care', ... }, ... { id: 849, name: 'ZZ Top Homes for the Aged', ... } ] } ``` {% endtab %} {% endtabs %} #### Example Usage {% tabs %} {% tab title="jQuery" %} ```javascript var settings = { "url": "https://api.tiny.plus/v2/companies?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/companies?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 Company `POST` `https://api.tiny.plus/v2/companies` You can create a new tiny+ company with this endpoint. The only required field to create a Company 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": "Auchenflower Aged Care",
"record\_status": "prospect",
"assigned\_user": 27110,
"description": "A large aged care provider based in Queensland, Australia."
....
}

| {% 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 Company `PATCH` `https://api.tiny.plus/v2/companies/{{id}}` You can edit a tiny+ Company with this endpoint. Note: you only need to pass the field you wish to change. #### Path Parameters | Name | Type | Description | | ---- | ------ | ------------------ | | id | number | ID of the company. | #### 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 |

{
"record\_status": "active",
"assigned\_user": 27111
....
}

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

String (up to 200 characters).

REQUIRED.

| Company Name. | Full | | description | String | Description. | Full | | created\_date | String (YYYY-MM-DD hh:mm:ss) | Date record was first created. | Read-only | | modified\_date | String (YYYY-MM-DD hh:mm:ss) | 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 relationship status of the Company. Note that this status field is intended for client companies, so non-client companies should not recieve a relationship status. Values you can use: prospect, active, latent, "" - ie blank.

When adding or editing a company, if your account is using additional phases for company relationship 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 | | external\_url | String or JSON object |

A link to this company 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 |