Record types and your account's fields

Record types

Each record type has its own URL, listed on the Endpoints 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:

{
    "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 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.
address	The address in parts, as described under 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.

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 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:

{ "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.

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.

Records include a tags field, listing their tags. Listing, filtering and paging 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:

[
    { "id": "195", "key": "proposal|195", "label": "Proposed - Long Term" },
    { "id": "won", "key": "won|0", "label": "Won!" },
    ...
]

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.

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.