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

# Connect

<mark style="color:blue;">`GET`</mark> `https://api.tiny.plus/v2/connect`

Who to contact this week, and why, as the [Connect](https://docs.tiny.plus/guides/everyday/connect.md) board shows it under Contacts. Each column is a reason: a follow-up is due, a live bid has gone quiet, a key client is going quiet, or someone is new or has moved. A person is on the board once, under the first reason that fits, and their card says the reason in words.

These endpoints read the board and one person, and do what a card's buttons do: Log, Later, Not needed and Undo. [`/me`](https://docs.tiny.plus/api/endpoints/me.md) lists `connect` in `api_features` where they exist. A day is `YYYY-MM-DD` in the token user's time zone, and a moment is UTC.

## The board

```bash
curl "https://api.tiny.plus/v2/connect" \
  -H "Authorization: Bearer {{user_access_token}}"
```

| Parameter | Description                                                                                                                                                                 |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `who`     | Whose cards: a key from `choices`. Read with, not kept. Without it you get the choice the person last kept, or their own. A choice the person doesn't have gives their own. |

```json
{
    "who": { "key": "s187", "label": "Mine", "mine": true },
    "choices": [
        { "key": "s187", "label": "Mine", "group": null },
        { "key": "", "label": "Everyone", "group": null },
        { "key": "t228967", "label": "Sydney", "group": "Teams" },
        { "key": "s191", "label": "Maya Lin", "group": "People" }
    ],
    "people": 12,
    "late": 3,
    "columns": [
        {
            "key": "due",
            "name": "Follow-up due",
            "hint": "Tasks and plan follow-ups due this week, or late",
            "count": 4,
            "may": { "later": false, "not_needed": false },
            "cards": [
                {
                    "id": 164583,
                    "name": "Anna Kowalski",
                    "job_title": "Head of Retail Development",
                    "company": { "id": 164567, "name": "Marlow & Finch" },
                    "url": "https://crm.tiny.plus/contact/164583",
                    "column": "due",
                    "why": "Follow-up was due Mon 12 Oct",
                    "tone": "late",
                    "also": "Catch-up: Anna Kowalski · Monthly catch-up",
                    "subject_id": null,
                    "last": { "at": "2026-10-02 02:42:41", "on": "2026-10-02", "how": "task", "logged": null, "words": "a task done" },
                    "people": [ { "id": 187, "name": "Laurence Persimmon" } ],
                    "task_id": 164637,
                    "plan_id": 164633
                }
            ]
        },
        { "key": "bids", "name": "Live bids, gone quiet", "hint": "On an open proposal, no contact for 21 days", "count": 5, "may": { "later": true, "not_needed": true }, "cards": [] },
        { "key": "clients", "name": "Key clients going quiet", "hint": "At a current client or prospect, no contact for 90 days", "count": 2, "may": { "later": true, "not_needed": false }, "cards": [] },
        { "key": "new", "name": "New or moved", "hint": "Just added, just met, or changed company", "count": 1, "may": { "later": true, "not_needed": true }, "cards": [] }
    ],
    "later": [
        { "key": "week", "label": "In a week" },
        { "key": "month", "label": "In a month" },
        { "key": "quarter", "label": "In 3 months" }
    ],
    "touch_types": [
        { "key": "call", "label": "Call", "button": "Log call" },
        { "key": "meeting", "label": "Meeting", "button": "Log meeting" }
    ],
    "settings": { "bid_days": 21, "client_days": 90, "new_days": 30, "moved_days": 90, "statuses": ["active", "prospect"] },
    "today": "2026-11-11",
    "web_url": "/contacts/connect"
}
```

| Field            | Description                                                                                                                                                                                                                                                                                                                                                            |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `who`            | Whose cards these are. `mine` is true when they are the token user's own.                                                                                                                                                                                                                                                                                              |
| `choices`        | What the person may choose: their own, then everyone's and their teams, then people. A key is `s` and a team member's id, `t` and a team's id, or empty for everyone. Empty when the person has no choice. A Reports Admin may choose anyone's, a team's or everyone's; others may choose a team of theirs where the account's team settings let them see its records. |
| `people`, `late` | How many people are on the board, and how many of the follow-ups are overdue.                                                                                                                                                                                                                                                                                          |
| `columns`        | The four reasons, always in this order. `count` is everyone in the column, and `cards` its first 60. `may` says whether a card there can be put away (`later`) or have its reason dropped (`not_needed`).                                                                                                                                                              |
| `later`          | The choices for putting a card away.                                                                                                                                                                                                                                                                                                                                   |
| `touch_types`    | The nine kinds of contact that can be logged, with the words for the button. `any` is "Other".                                                                                                                                                                                                                                                                         |
| `settings`       | The account's day counts and the company statuses whose people count as key. Account admins set them on the web.                                                                                                                                                                                                                                                       |

A card:

| Field                | Description                                                                                                                                                                                                                                                                                                                          |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                 | The contact's id.                                                                                                                                                                                                                                                                                                                    |
| `why`, `also`        | The reason in words, and a second line or `null`: the task behind a follow-up, a bid's name, or another reason. Written for the person; show them as given.                                                                                                                                                                          |
| `tone`               | `late`, `quiet` or `news`.                                                                                                                                                                                                                                                                                                           |
| `subject_id`         | What the reason is about: the project, the event, or the company they left. `null` where there's none. Send it back with Not needed.                                                                                                                                                                                                 |
| `last`               | The last time anyone was in touch that the token user may see, or `null` for never. `how` is `meeting`, `post`, `task` or `email`. A post [logged as contact](https://docs.tiny.plus/api/endpoints/updates.md#logging-contact-with-a-person) says what it was in `logged`, and `words` puts either in words ("a call", "a meeting"). |
| `people`             | Team members who were in touch in the last 12 months.                                                                                                                                                                                                                                                                                |
| `task_id`, `plan_id` | On a follow-up's card, the task that is due, and the [relationship plan](https://docs.tiny.plus/api/endpoints/relationship-plans.md) it belongs to, if any.                                                                                                                                                                          |

"In touch" means a meeting held with the person on it, a post someone wrote about them, a task done that names them, or an email: one [saved against them](https://docs.tiny.plus/api/endpoints/emails.md), counted on the day it was saved, or one captured from Microsoft 365. Confidential notes don't count, and a meeting, post, task or email the token user can't open isn't counted for them.

### Keeping whose cards

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

```bash
curl -X POST "https://api.tiny.plus/v2/connect/scope" \
  -H "Authorization: Bearer {{user_access_token}}" \
  -H "Content-Type: application/json" \
  -d '{ "who": "t228967" }'
```

```json
{
    "who": { "key": "t228967", "label": "Sydney", "mine": false }
}
```

The board opens on it next time, here and on the web. A choice the person doesn't have is `400`.

## One person

<mark style="color:blue;">`GET`</mark> `https://api.tiny.plus/v2/connect/{contact_id}`

```bash
curl "https://api.tiny.plus/v2/connect/164583" \
  -H "Authorization: Bearer {{user_access_token}}"
```

```json
{
    "id": 164583,
    "name": "Anna Kowalski",
    "job_title": "Head of Retail Development",
    "company": { "id": 164567, "name": "Marlow & Finch" },
    "url": "https://crm.tiny.plus/contact/164583",
    "last": { "at": "2026-11-10 21:56:46", "on": "2026-11-11", "how": "post", "logged": "call", "words": "a call" },
    "next_meeting": null,
    "recent": [
        { "at": "2026-11-10 21:56:46", "on": "2026-11-11", "how": "post", "logged": "call", "words": "a call", "what": "Spoke about the stage two fee.", "staff": { "id": 1, "name": "Nick Smith" } }
    ],
    "people": [
        { "id": 187, "name": "Laurence Persimmon", "in_touch": true, "on_team": false }
    ],
    "tasks": [
        { "id": 164637, "name": "Catch-up: Anna Kowalski", "due": "2026-10-12", "staff": { "id": 187, "name": "Laurence Persimmon" }, "plan_id": 164633 }
    ],
    "proposals": [
        { "id": 251843, "name": "Library fit-out", "due": "2026-11-20" }
    ],
    "plan": { "status": "overdue", "label": "Overdue", "due": "2026-10-12" }
}
```

Any contact the token user can open, whether or not they are on the board. `recent` is their last six touches, newest first. `people` are team members who were in touch in the last 12 months (`in_touch`) or are on the contact's team (`on_team`). `tasks` are the open, dated tasks that name them; `proposals` the open proposals they are on; `plan` their company's relationship plan, or `null`. A contact that doesn't exist, or that the person can't open, is `404`.

## Logging contact

<mark style="color:green;">`POST`</mark> `https://api.tiny.plus/v2/connect/{contact_id}/log`

```bash
curl -X POST "https://api.tiny.plus/v2/connect/164583/log" \
  -H "Authorization: Bearer {{user_access_token}}" \
  -H "Content-Type: application/json" \
  -d '{
        "touch_type": "call",
        "date": "2026-11-10",
        "notes": "Spoke about the stage two fee. She will send the brief on Friday.",
        "next_date": "2026-11-25"
      }'
```

```json
{
    "update_id": 251901,
    "task_id": 251902,
    "message": "Logged, and a follow-up booked for Wed 25 Nov."
}
```

| Field        | Description                                                                                                                                                                      |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `touch_type` | A key from `touch_types`. A call when left out.                                                                                                                                  |
| `date`       | The day it happened. Today when left out. A day still to come is `400`.                                                                                                          |
| `notes`      | What was said. They become a [post](https://docs.tiny.plus/api/endpoints/updates.md) about the contact, shown on their company as well. Left out, the post says what was logged. |
| `next_date`  | A day, today or later. Books a task for the token user called "Follow up" with the contact's name, due that day.                                                                 |
| `task_id`    | The card's `task_id`: the follow-up this was, which is marked done.                                                                                                              |

`update_id` is the post, and `task_id` the follow-up it booked, or `null`. The person leaves the board's quiet columns at once.

A follow-up that belongs to a relationship plan (the card's `plan_id`) is logged on the plan, with [`POST /v2/relationship_plans/{id}/touches`](https://docs.tiny.plus/api/endpoints/relationship-plans.md). Sent here it is `409`.

## Later and Not needed

<mark style="color:green;">`POST`</mark> `https://api.tiny.plus/v2/connect/{contact_id}/later`

```bash
curl -X POST "https://api.tiny.plus/v2/connect/164583/later" \
  -H "Authorization: Bearer {{user_access_token}}" \
  -H "Content-Type: application/json" \
  -d '{ "column": "clients", "until": "month" }'
```

```json
{
    "until": "2026-12-11",
    "message": "Put away until Fri 11 Dec."
}
```

| Field        | Description                                                                                                                                                             |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `column`     | The card's column. A follow-up that is due can't be put away: move or log its task.                                                                                     |
| `until`      | `week`, `month`, `quarter`, or a day within the next two years. `never` is **Not needed**: the reason is dropped for good, where the column's `may.not_needed` is true. |
| `subject_id` | With `never`, the card's `subject_id`: which bid, event or move is dropped.                                                                                             |

It changes the token user's board only. A colleague still sees the card.

<mark style="color:red;">`DELETE`</mark> `https://api.tiny.plus/v2/connect/{contact_id}/later?column=clients`

Undo: the card is back on the board. Add `subject_id` to bring back a reason that was dropped.

## Errors

| Status | Means                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `400`  | A day that can't be used, a column or a choice that doesn't apply, or a card that can't be put away. The `error` says which. |
| `403`  | The task belongs to someone else and the token user may not change it.                                                       |
| `404`  | No such contact, or one the token user can't open.                                                                           |
| `409`  | The follow-up is a relationship plan's. Log it on the plan.                                                                  |
