> 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/concepts/record-types.md). # Record types and your account's fields ## Record types Each record type has its own URL, listed on the [Endpoints](/api/endpoints.md) page. Some of them differ from the names used in tiny+: | In tiny+ | In the API | | ------------ | ------------ | | Tasks | `activities` | | Team members | `staff` | | Posts | `updates` | ## Your account's fields Every tiny+ account is set up a little differently: * An account can rename the standard fields of each record type, and make some of them required. * It can add custom fields and tag collections. * It can choose its own statuses, and split statuses into phases. The field reference on each record type's page lists the standard fields. To see what your account has, use: | Request | Returns | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET /v2/fields/{type}` | The standard fields, keyed by field name. Each has a label (`field_description`), a `field_type`, whether it can be changed (`field_allowedit`) and whether it's required (`val_required`). List fields also have their `options`. Custom fields and tags aren't included. | | `GET /v2/form_structure/{type}/view` | The record type's view form, in groups. This is where custom fields (`custom_{id}`) and tag collections (`tags_{id}`, with each tag's `id`, `name` and `colour`) are listed. | | `GET /v2/record_status/{type}` | The values `record_status` accepts. For a status split into phases you get one entry per phase, and the status itself isn't listed; otherwise one entry per status. | For example, part of `GET /v2/fields/projects`: ```json { "record_status": { "field_name": "record_status", "field_type": "fancy_select", "field_description": "Project Status", "field_allowedit": "1", "options": [ { "value": "proposal", "label": "Proposed", "colour": "#62c989" }, { "value": "won", "label": "Won!", "colour": "#1cb5e8" }, ... ] }, ... } ``` These change rarely, so read them once and keep a copy. Don't read them before every request. The [Account structure](/api/endpoints/account-structure.md) page describes each of these endpoints in full. ## Sending values When you create or update a record, send each field in the form its `field_type` expects: | `field_type` | Send | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `varchar`, `text`, `email`, `phone`, `url` | A string. | | `int`, `percentage` | A whole number. | | `currency`, `multicurrency` | A number, such as `42000`. Amounts are kept in whole units, so cents are dropped. Written forms such as `$42k` or `1,500,000` work too. | | `date`, `due_date` | `YYYY-MM-DD`. | | `datetime` | `YYYY-MM-DD hh:mm:ss`, in UTC. Date-times are stored as you send them, and come back in UTC. | | `bit` | `1` for yes, `0` for no. | | `select`, `fancy_select` | The `value` of one of the field's `options`. | | `staff` | A team member's id. | | `id` | A record's id. See [Linking records](/api/concepts/linking.md). | | `address` | The address in parts, as described under [Addresses](/api/endpoints/companies.md#addresses). A single line of text clears it. | | `duration` | An ISO 8601 duration, such as `P4M` for four months. | | `timezone` | A time zone name, such as `Australia/Sydney`: one of the field's `options`, or any other IANA zone name. Anything else gets a `400`. See [Time zone](/api/endpoints/team-members.md#time-zone). | ## Custom fields Custom fields are named `custom_{id}`, for example `custom_6911`. Send them like any other field, in the form their type expects. Send an empty string to clear one. [Filtering](/api/concepts/listing.md#filtering) explains which custom fields a list can be filtered on. ## Tags Each tag collection is a field named `tags_{collection id}`. To set a record's tags in a collection, send an array of tag ids: ```json { "tags_1311": ["1312", "1313"] } ``` * This replaces the record's tags in that collection. Its tags in other collections are left alone. * A single tag id, sent as a string, works too. * An empty array clears the collection, unless the collection is required. {% hint style="warning" %} Don't send tag ids as a comma-separated string, such as `"1312,1313"`. It isn't split: it's read as one unknown tag, and clears the collection. {% endhint %} Records include a `tags` field, listing their tags. [Listing, filtering and paging](/api/concepts/listing.md) explains when lists leave tags out. ## Statuses and phases `record_status` takes a status, such as `won`. On accounts that split statuses into phases, it also takes a phase id. A phase id sets both `record_status`, to the status the phase belongs to, and `record_phase`. `GET /v2/record_status/{type}` lists what your account accepts. Send the `id` of the one you want: ```json [ { "id": "195", "key": "proposal|195", "label": "Proposed - Long Term" }, { "id": "won", "key": "won|0", "label": "Won!" }, ... ] ``` {% hint style="warning" %} When a status has phases, send one of its phase ids, not the status. If you update a project with a status that has phases, such as `proposal`, the change is ignored, though the response is still `{"results": true}`. A new project or company created with such a status starts in its first phase. {% endhint %} ## Names of linked records When you get one record, each field that holds another record's id comes with a `{field}_name` companion holding that record's name, for example `primary_company_id_name`.