# Contacts ## Get a Contact `GET` `https://api.tiny.plus/v2/contacts/{{id}}` This endpoint allows you to get a full Contact record. #### Path Parameters | Name | Type | Description | | ---- | ------ | ----------------- | | id | number | ID of the contact | #### 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 Contact successfully retrieved." %} ```javascript { "id": 1241 "name": "Adam Adamson", "first_name": "Adam", "last_name": "Adamson", "email_address": "adam@adamson.com", "primary_company": 1237, "title": "CEO", "assigned_user": 1231, ... } ``` {% endtab %} {% tab title="404 Could not find a contact matching the provided ID." %} ```javascript { "message": "Contact not found." } ``` {% endtab %} {% endtabs %} #### Example Usage {% tabs %} {% tab title="jQuery" %} ```javascript var settings = { "url": "https://api.tiny.plus/v2/contacts/{{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/contacts/{{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 Contacts `GET` `https://api.tiny.plus/v2/contacts` This endpoint allows you to get a paginated list of Contacts, 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 contacts for user 1232:
/contacts/?assigned\_user=1232

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

| | 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 Related Team Members. | | 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 Related Team Members, *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/contacts?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/contacts?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 Contact `POST` `https://api.tiny.plus/v2/contacts` You can create a new tiny+ contact with this endpoint. The only required field to create a Contact in tiny+ is `name`, however we recommend you provide as much information as possible. #### Query Parameters | Name | Type | Description | | -------------- | ------- | ----------------------------------------------------------------------------------- | | return\_record | boolean | Add this parameter to get a copy of the newly created record. Save yourself a call! | #### 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": "Alex Amorosi",
"assigned\_user": 27110,
"title": "Founder",
"direct\_tel": "02 9911 0222",
"email\_address": ""
....
}

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

{
"assigned\_user": 27111,
"direct\_tel": "02 9999 1020"
}

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

String (up to 200 characters).

REQUIRED.

| Contact Name. eg. `Andrew Anderson` | Full | | first\_name | String | Optionally, you can create / edit a contact as First Name and Last Name instead of the **name** field. If you do not provide this field, we will generate this value based on the name field. | Full | | last\_name | String | (As above) | 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\_url | String | The fully qualified URI of the record. | Read-only | | title | String | The title or position of this contact. eg. `Development Director`. | Full | | email\_address | String (Email Address) | Must be a valid email address in RFC 822 syntax. Invalid entries are ignored. | Full | | linkedin | String | A URL to the contact's LinkedIn page. | Full | | twitter | String | A Twitter @handle. | Full | | mobile | String | Mobile telephone number. | Full | | office\_tel | String | Office telephone number. | Full | | direct\_tel | String | Direct Line telephone number. | Full | | physical\_address1 | String | Address - Line 1 | Full | | physical\_address2 | String | Address - Line 2 | Full | | physical\_town | String | Address - the Town/City/Locality. | Full | | physical\_state | String | Address - the State or Province. | Full | | physical\_postcode | String | Address - the Postal Code or Region Code. | Full | | physical\_country | String | Address - the Country. | Full | | external\_url | String or JSON object |

A link to this contact 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 | | notes | String | A space for extra notes about this contact. | 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/contacts.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.