> 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/contacts.md). # Contacts Contacts live at `/v2/contacts`. They support every request on the [Records](/api/endpoints/records.md) page: list, get, history, create, update, delete and search. ## Creating a contact ```bash curl -X POST "https://api.tiny.plus/v2/contacts" \ -H "Authorization: Bearer {{user_access_token}}" \ -H "Content-Type: application/json" \ -d '{ "first_name": "Alex", "last_name": "Amorosi", "title": "Founder", "email_address": "alex@example.com", "direct_tel": "02 9911 0222", "primary_company": "1237" }' ``` ```javascript { "id": "161080" } ``` A new contact's `record_status` is `active` unless you send another. ## Names A contact has a `name`, and a `first_name` and `last_name`: * Send `first_name` and `last_name`, and `name` is made from them: "Alex Amorosi". * Send only `name`, and it's split at the last space. `last_name` is the last word, and `first_name` is everything before it. On an update, this replaces the contact's first and last names. * Send all three, and they're kept as you sent them. ## Email address Send the contact's email address as `email_address`. It's stored in lower case. An address that isn't valid is dropped without an error. Two contacts can share an address. A contact you read has both `email_address` and `email_id`. `email_id` is tiny+'s own id for the address, not the address itself. ## Company A contact's company is its `primary_company`. Send the company's id, or its name: a name is matched exactly, and a new company is created if there's no match. The company a contact was linked to before stays linked. See [Linking records](/api/concepts/linking.md). ## Addresses A contact has two addresses, `physical_address` and `postal_address`. Send each one's parts after the field's name, together with the field itself set to an empty value: ```javascript { "physical_address": "", "physical_address_address1": "1 Queen St", "physical_address_town": "Melbourne", "physical_address_state": "VIC", "physical_address_postcode": "3000", "physical_address_country": "Australia" } ``` The parts are `_address1`, `_address2`, `_town`, `_state`, `_postcode` and `_country`. {% hint style="warning" %} A contact's addresses come back under shorter names than the ones you send: `physical_address1`, `physical_address2`, `physical_town`, `physical_state`, `physical_postcode` and `physical_country`, and the same for `postal_`. Sending an address as one line of text, without its parts, clears it. {% endhint %} ## Finding contacts The contacts at one company, with their email addresses: ```bash curl "https://api.tiny.plus/v2/contacts?primary_company=1237&fields=id,name,title,email_address&return_format=array&with_related=0" \ -H "Authorization: Bearer {{user_access_token}}" ``` ```javascript { "total_records": 1, "returned_records": 1, "records": [ { "id": "161080", "name": "Alex Amorosi", "title": "Founder", "email_address": "alex@example.com", "show_obscured": false } ] } ``` To find a contact by email address, filter on it: `GET /v2/contacts?email_address=alex@example.com`. ## Fields | Field | Label in tiny+ | Type | Notes | Editable | | ------------------------------- | ------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `dietary_reqs` | Dietary Requirements | Text | | Yes | | `direct_tel` | Direct Line | Phone number | | Yes | | `email_id` | Email Address | Text | tiny+'s id for the contact's email address. Send and read the address itself as `email_address`: see [Email address](#email-address). | No | | `first_name` | First Name | Text | See [Names](#names). | Yes | | `last_name` | Last Name | Text | See [Names](#names). | Yes | | `linkedin` | LinkedIn | URL | Up to 1000 characters. | Yes | | `mobile` | Mobile Phone | Phone number | | Yes | | `name` | Full Name | Text | Required. The contact's full name. See [Names](#names). Up to 200 characters. | Yes | | `notes` | Notes | Text | | Yes | | `office_tel` | Office Phone | Phone number | | Yes | | `owner` | Contact Owner | Team member id | The team member who owns the contact. | Yes | | `physical_address` | Contact Address | Address | Send it in parts: see [Addresses](#addresses). Reads return `physical_address1`, `physical_address2`, `physical_town`, `physical_state`, `physical_postcode` and `physical_country`. | Yes | | `postal_address` | Contact Address 2 | Address | Send it in parts: see [Addresses](#addresses). Reads return `postal_address1`, `postal_address2`, `postal_town`, `postal_state`, `postal_postcode` and `postal_country`. | Yes | | `primary_company` | Related Company | Record id | The contact's company: its id, or a name to match or create. See [Company](#company). | Yes | | `primary_company_assigned_user` | Related Company Assigned | Team member id | The team member the contact's company is assigned to. | No | | `primary_company_record_status` | Related Company Status | Option | The contact's company's status. | No | | `record_status` | Contact Status | Option | The contact's status. `active` unless you send another. | Yes | | `salutation` | Salutation | Text | Up to 50 characters. | Yes | | `title` | Title | Text | | Yes | | `twitter` | Twitter Handle | Text | | Yes |