> 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/linking.md).

# Linking records

Records in tiny+ are linked to each other. A project is linked to its client company and contacts, a contact to their company, and team members to the records they work on.

## Reading links

Get a record with `with_related=1` to see what it's linked to. Links are returned in a `related` object, grouped by record type and keyed by id. Team members are under `staff`:

```bash
curl "https://api.tiny.plus/v2/projects/{{id}}?with_related=1" \
  -H "Authorization: Bearer {{user_access_token}}"
```

```javascript
{
    "id": "1343",
    "name": "10 Downing Street",
    "related": {
        "companies": { "1237": { "id": "1237", "name": "Auchenflower Aged Care", ... } },
        "staff": { "1231": { "id": "1231", "name": "Alex Example", ... } },
        ...
    },
    ...
}
```

Lists include `related` by default, but only on pages of 50 records or fewer. See [Listing, filtering and paging](/api/concepts/listing.md).

## Linking a client company

A project's client company is its `primary_company_id`. When you create or update a project, you can send:

* **a company's id**, to link that company;
* **a company's name.** If a company with exactly that name exists, it's linked. If not, a new company is created with that name and linked. Names of two characters or fewer are ignored.

The company the project was linked to before stays linked. It just isn't the primary company any more.

A contact's company is its `primary_company`, and works the same way: send a company's id, or its name.

## Linking other records

`related_selector` links records to the one you're creating or updating. Send one or more record ids as strings, either as an array or as a comma-separated string:

```json
{ "related_selector": ["1231", "1245"] }
```

* It works on every record type, and the ids can be any kind of record, team members included.
* A team member linked this way is added to the record's team, subscribed to it, and notified. Add `"dont_track": 1` to skip the notification.
* Ids of deleted records, or of records in another account, are skipped.
* `related_selector` only adds links; it can't remove them.
* Updating a record needs permission to change it. To join a record's team without that permission, use `join_team` instead.

## Joining and leaving a team

The token's user can join or leave a record's team:

<mark style="color:green;">`POST`</mark> `https://api.tiny.plus/v2/actions`

| Body                                        | Does                                        |
| ------------------------------------------- | ------------------------------------------- |
| `{"do": "join_team", "id": "{record id}"}`  | Adds the token's user to the record's team. |
| `{"do": "leave_team", "id": "{record id}"}` | Takes them off it.                          |

Joining needs no permission to change the record, and works on any record type. It answers:

| Case                                                          | Response                                                                                      |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Joined                                                        | `200` `{"response": "added"}`                                                                 |
| Already on the team                                           | `200` `{"response": "already_added"}`                                                         |
| The record is confidential, and the token's user can't see it | `403`                                                                                         |
| No such record                                                | `400` `{"error": "Could not complete action. You may not have the appropriate permissions."}` |

Leaving answers `200` with `{"status": "success", "error_code": 0, "message": "Left team for project", "response": 0}`. It gives the same answer if they weren't on the team. It doesn't unsubscribe them from the record.

To take other links off a record, use tiny+ itself.