> 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/companies.md). # Companies Companies live at `/v2/companies`. They support every request on the [Records](/api/endpoints/records.md) page: list, get, history, create, update, delete and search. ## Creating a company ```bash curl -X POST "https://api.tiny.plus/v2/companies" \ -H "Authorization: Bearer {{user_access_token}}" \ -H "Content-Type: application/json" \ -d '{ "name": "Auchenflower Aged Care", "record_status": "prospect", "telephone": "07 3000 0000", "website": "https://example.com", "assigned_user": "1231" }' ``` ```javascript { "id": "161031" } ``` `name` is the only field a company needs. A company created with a status that has phases, like `prospect` here, starts in that status's first phase. ## Finding companies Your current clients, by name: ```bash curl "https://api.tiny.plus/v2/companies?record_status=active&sort=name&fields=id,name,telephone,website&return_format=array&with_related=0" \ -H "Authorization: Bearer {{user_access_token}}" ``` ```javascript { "total_records": 42, "returned_records": 15, "records": [ { "id": "1237", "name": "Auchenflower Aged Care", "telephone": "07 3000 0000", "website": "https://example.com", "show_obscured": false }, ... ] } ``` To find a company by name, use [search](/api/endpoints/records.md#search): `GET /v2/search/companies?q=auchenflower`. ## Relationship status A company's `record_status` is its relationship with you, such as `prospect`, `active` (a current client) or `latent` (a past client). `GET /v2/record_status/companies` lists your account's statuses and phases. [Statuses and phases](/api/concepts/record-types.md#statuses-and-phases) explains how to set them. ## Addresses A company has two addresses, `company_address` and `postal_address`. To set one, send the address field itself with an empty value, together with its parts: ```javascript { "company_address": "", "company_address_address1": "10 Eagle St", "company_address_address2": "", "company_address_town": "Brisbane", "company_address_state": "QLD", "company_address_postcode": "4000", "company_address_country": "Australia" } ``` The parts are the field's name followed by `_address1`, `_address2`, `_town`, `_state`, `_postcode` and `_country`. For the postal address, that's `postal_address_address1` and so on. tiny+ finds the address on the map afterwards, and returns its position as `company_address_geo_lat` and `company_address_geo_lng`. {% hint style="warning" %} Sending an address as one line of text, without its parts, clears it. {% endhint %} When you read a company, `company_address` comes back as the parts you sent, `company_address_address1` to `company_address_country`. The postal address comes back under shorter names: `postal_address1`, `postal_address2`, `postal_town`, `postal_state`, `postal_postcode` and `postal_country`. ## A company's projects and contacts A project is linked to its client company through the project's `primary_company_id`, and a contact to their company through the contact's `primary_company`. To see everything a company is linked to, get it with `with_related=1`. Its `related` object includes its projects, with their fee, status and tags, and its contacts, with their names and titles. See [Linking records](/api/concepts/linking.md). ## Fields | Field | Label in tiny+ | Type | Notes | Editable | | ----------------------- | ------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `ABN` | ABN | Text | Australian Business Number. Up to 20 characters. | Yes | | `ACN` | ACN | Text | Australian Company Number. Up to 20 characters. | Yes | | `assigned_user` | Assigned To | Team member id | A team member's id. | Yes | | `combined_value` | Lifetime & Pipeline Value | Amount | | No | | `company_address` | Company Address | Address | The company's address. Send it in parts: see [Addresses](#addresses). Reads return `company_address_address1` to `company_address_country`, and `company_address_geo_lat` and `company_address_geo_lng`. | Yes | | `email` | E-mail | Email address | | Yes | | `fax` | Fax | Text | | Yes | | `health_rating` | Health | Health | The relationship's health, from 0 to 100. tiny+ works it out daily. | No | | `lifetime_value` | Lifetime Value | Amount | | No | | `mobile` | Mobile | Text | | Yes | | `name` | Company Name | Text | Required. The company's name. Up to 200 characters. | Yes | | `notes` | Notes | Text | | Yes | | `pipeline_value` | Pipeline Value | Amount | | No | | `postal_address` | Postal Address | Address | The company's postal address. Send it in parts: see [Addresses](#addresses). Reads return it as `postal_address1`, `postal_address2`, `postal_town`, `postal_state`, `postal_postcode` and `postal_country`. | Yes | | `rating` | Rating | Rating | A whole number. | Yes | | `record_status` | Relationship Status | Option | The relationship status, or a phase id: see [Statuses and phases](/api/concepts/record-types.md#statuses-and-phases). | Yes | | `summary` | Relationship Summary | Text | A summary of the relationship. | Yes | | `summary_modified_date` | Summary Change Date | Date-time | In UTC. When the summary last changed. | No | | `summary_modified_user` | Summary Changed By | Team member id | The team member who last changed the summary. | No | | `telephone` | Telephone | Text | | Yes | | `twitter` | Twitter Handle | Text | | Yes | | `website` | Website | URL | | Yes |