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

# Bid teams

A firm often bids for one project through several competing teams, each led by another firm: the lead firm. A project's bid teams list each team the firm is on, with its fee to that team, the team's chance of winning, when the proposal is due to the lead firm and how the team did. While a team is still in the running, the project's fee and probability are worked out from its teams, and a win or the last team going out closes the project.

Bid teams have endpoints of their own. They aren't a [record type](https://docs.tiny.plus/api/endpoints/records.md), so the list filters, search and the generic create, update and delete requests don't apply to them. The [Bid teams guide](https://docs.tiny.plus/guides/everyday/bid-teams.md) shows how they work in tiny+ itself.

| Request                               | What it does                                                                       |
| ------------------------------------- | ---------------------------------------------------------------------------------- |
| `GET /v2/bid_teams?project_id={id}`   | [The teams on a project](#the-teams-on-a-project), and what they make of it.       |
| `GET /v2/bid_teams?company_id={id}`   | [The teams under a lead firm](#the-teams-under-a-lead-firm), with its two numbers. |
| `GET /v2/bid_teams/{id}`              | [One team](#one-team).                                                             |
| `POST /v2/bid_teams`                  | [Adds a team](#add-a-team) to a project.                                           |
| `PATCH /v2/bid_teams/{id}`            | [Changes a team](#change-a-team), or its result.                                   |
| `PATCH /v2/bid_teams?project_id={id}` | Sets [how many teams are bidding](#how-many-teams-are-bidding).                    |
| `DELETE /v2/bid_teams/{id}`           | [Takes a team off](#remove-a-team) its project.                                    |

Four things differ from the record endpoints:

* **Ids are numbers**, not strings.
* **Text is plain.** Names and notes come back as typed, not HTML-escaped.
* **Times are UTC**, as `2026-10-11T05:34:00Z`. A date with no time is `YYYY-MM-DD`.
* **Errors are sentences** written for the person using your app: `{"error": "That team could not be found."}`. See [Errors](#errors).

## Is it switched on?

Bid teams come with the Pro plan, and are off until an account admin turns them on under Account Settings → Projects. [`/me`](https://docs.tiny.plus/api/endpoints/me.md#integrations) carries `integrations.bid_teams`, which is `true` while they're on. While they're off, every request here answers `403`, and the teams are kept for when they're turned on again:

```json
{
    "error": "Bid teams aren't available on this account."
}
```

## Who sees a team

A team is read through its project. The token's user sees a project's teams when they can open the project. A [confidential](https://docs.tiny.plus/api/concepts/permissions.md#confidential-records) project they can't open answers `404`, as if it had no teams, and its teams are left out of a lead firm's. A confidential lead firm or contact they can't see is named "(Confidential company)" or "(Confidential contact)".

A team's fee shows where the project's fee would. Where the token's user can't see a project's Project Fee, `fees_shown` is `false`, and the team's `fee`, `fee_entered` and `fee_currency` and the project's `fee_value` are `null`.

Changing a project's teams needs edit rights on the project. Setting a team's fee or chance also needs the right to change the project's fee, which its owners, its team and records admins have.

## The teams on a project

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

The teams come in the order the project shows them. There is no paging.

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

```json
{
    "project": {
        "id": 195414,
        "name": "Tasman Health new wing",
        "record_status": "proposal",
        "record_phase": 195,
        "record_status_display": "Long Term",
        "open": true,
        "probability": 60,
        "fee_value": "110000.00",
        "fee_from_stages": false,
        "proposal_due_date": "2026-11-07",
        "client": {
            "id": 164564,
            "name": "Tasman Health"
        },
        "tender_teams": 5,
        "default_chance": 20,
        "live_teams": 3,
        "chance_total": 60,
        "closed_by_teams": false,
        "record_url": "https://crm.tiny.plus/project/195414"
    },
    "can_change": true,
    "can_set_fee": true,
    "fees_shown": true,
    "records": [
        {
            "id": 195,
            "project_id": 195414,
            "lead_firm": {
                "id": 164567,
                "name": "Marlow & Finch",
                "deleted": false
            },
            "contact": {
                "id": 164579,
                "name": "Ben Okafor",
                "deleted": false
            },
            "fee": "120000.00",
            "fee_entered": "120000.00",
            "fee_currency": "AUD",
            "chance": 20,
            "due_date": "2026-10-24",
            "result": "in_bid",
            "result_display": "In the bid",
            "live": true,
            "result_date": "2026-10-11T05:36:44Z",
            "picked_date": "2026-10-11T05:34:00Z",
            "note": "Their structural engineer asked for our health-sector references.",
            "task": {
                "id": 195420,
                "status": "completed"
            },
            "display_order": 0,
            "created_date": "2026-10-11T05:34:00Z",
            "modified_date": "2026-10-11T05:36:44Z"
        }
    ]
}
```

| Field         | Description                                                              |
| ------------- | ------------------------------------------------------------------------ |
| `project`     | The project, and what its teams make of it (below).                      |
| `can_change`  | Whether the token's user may add, change and remove the project's teams. |
| `can_set_fee` | Whether they may also set a team's fee and chance.                       |
| `fees_shown`  | Whether they can see the project's fee, and so its teams' fees.          |
| `records`     | The teams (below).                                                       |

### The project

| Field                           | Description                                                                                                                                         |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `record_status`, `record_phase` | The project's status, and its phase where it has one. `record_status_display` names the phase, or else the status.                                  |
| `open`                          | Whether the project is still a proposal. Only then are its fee and probability worked out from its teams.                                           |
| `probability`, `fee_value`      | The project's probability and fee, in the account's currency. See [The fee and probability](#the-fee-and-probability).                              |
| `fee_from_stages`               | Whether the project's stages set its fee. Its teams then can't have fees of their own.                                                              |
| `proposal_due_date`             | The project's Proposal Due, which follows the teams still being prepared.                                                                           |
| `client`                        | The project's client company, or `null`. A win makes the winning team's lead firm the client.                                                       |
| `tender_teams`                  | How many teams are bidding in all, whether the firm is on them or not, or `null` when it isn't known.                                               |
| `default_chance`                | The chance a team in the running counts for when it has none of its own: 1 in `tender_teams`, as a whole percentage. `null` when `tender_teams` is. |
| `live_teams`                    | How many teams are still in the running.                                                                                                            |
| `chance_total`                  | The chances of the teams in the running, added up. Over 100, the project's probability stays at 100.                                                |
| `closed_by_teams`               | Whether the project was lost or cancelled because its last team went out.                                                                           |

### A team

| Field                         | Description                                                                                                                                                                      |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lead_firm`                   | The company leading the team, or `null` when the firm leads the team itself. `deleted` is `true` for a company deleted since: the team stays, so the numbers keep their history. |
| `contact`                     | The firm's contact at the lead firm, or `null`.                                                                                                                                  |
| `fee`                         | The firm's fee to this team, in the account's currency, or `null`.                                                                                                               |
| `fee_entered`, `fee_currency` | The fee as it was sent, and its currency. On accounts that use one currency, `fee_currency` is `null`.                                                                           |
| `chance`                      | The team's chance of winning, from `0` to `100`, or `null` to count for `default_chance`.                                                                                        |
| `due_date`                    | When the proposal is due to the lead firm.                                                                                                                                       |
| `result`                      | Where the team is: see [Results](#results). `result_display` is its name in tiny+, and `live` says whether it's still in the running.                                            |
| `result_date`                 | When the result last changed.                                                                                                                                                    |
| `picked_date`                 | When the lead firm put the firm on its team: the first time the team went into the bid. It stays if the firm later withdraws.                                                    |
| `note`                        | Free text, or `null`.                                                                                                                                                            |
| `task`                        | The due-date task, if one was made: its `id` and `status`, `open` while the team is being prepared.                                                                              |
| `display_order`               | The team's place in the list.                                                                                                                                                    |

## The teams under a lead firm

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

Every team the firm has been on under this lead firm, on projects the token's user can open: those still in the running first, the soonest due first, then the rest, the latest decided first.

| Parameter        | Description                                                                      |
| ---------------- | -------------------------------------------------------------------------------- |
| `limit`, `start` | 50 teams a page, 200 at most. Pass `next_start` as `start` to get the next page. |

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

```json
{
    "company": {
        "id": 164567,
        "name": "Marlow & Finch",
        "record_url": "https://crm.tiny.plus/company/164567"
    },
    "numbers": {
        "picked": 3,
        "asked": 4,
        "pick_rate": 75,
        "won": 1,
        "decided": 2,
        "win_rate": 50,
        "cancelled": 0
    },
    "total_records": 4,
    "returned_records": 4,
    "start": 0,
    "next_start": null,
    "records": [
        {
            "id": 195,
            "project_id": 195414,
            "lead_firm": {
                "id": 164567,
                "name": "Marlow & Finch",
                "deleted": false
            },
            "contact": null,
            "fee": "120000.00",
            "fee_entered": "120000.00",
            "fee_currency": "AUD",
            "chance": 20,
            "due_date": "2026-10-24",
            "result": "in_bid",
            "result_display": "In the bid",
            "live": true,
            "result_date": "2026-10-11T05:36:44Z",
            "picked_date": "2026-10-11T05:34:00Z",
            "note": null,
            "task": null,
            "display_order": 0,
            "created_date": "2026-10-11T05:34:00Z",
            "modified_date": "2026-10-11T05:36:44Z",
            "project": {
                "id": 195414,
                "name": "Tasman Health new wing",
                "record_status": "proposal",
                "record_url": "https://crm.tiny.plus/project/195414"
            }
        }
    ]
}
```

Each team is as [on a project](#a-team), with its `project`. A team's fee is `null` where the token's user can't see that project's fee.

`numbers` are the lead firm's two numbers, over every team listed, not just this page:

| Field                          | Description                                                                                                                                                                             |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `picked`, `asked`, `pick_rate` | How often the lead firm picks the firm for its team: the teams it put the firm on, out of those plus the ones it left the firm out of (`not_included`), and that as a whole percentage. |
| `won`, `decided`, `win_rate`   | How often its teams with the firm win: `won`, out of `won` plus `not_selected`.                                                                                                         |
| `cancelled`                    | Teams on cancelled projects, which count in neither.                                                                                                                                    |

A rate is `null` until there is something to count. A team still being prepared counts in neither number, and nor does one the firm withdrew from before it was picked.

## One team

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

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

The answer is the team, as [on a project](#a-team), with its `project` as [The teams on a project](#the-project) gives it.

## Add a team

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

| Field          | Description                                                                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `project_id`   | Required. The project the team bids for.                                                                                                         |
| `company_id`   | Required. The lead firm's id, or `null` for a team the firm leads itself.                                                                        |
| `contact_id`   | The firm's contact at the lead firm.                                                                                                             |
| `fee`          | The firm's fee to the team, such as `120000` or `"120k"`. In whole units: cents are dropped.                                                     |
| `fee_currency` | The fee's currency, on accounts that use more than one. Without it, the fee is in the project's currency, or else the account's.                 |
| `chance`       | The team's chance of winning, from `0` to `100`. Leave it out to count the team for `default_chance`.                                            |
| `due_date`     | When the proposal is due to the lead firm, as `YYYY-MM-DD`.                                                                                      |
| `result`       | `preparing`, unless you send another [result](#results).                                                                                         |
| `note`         | Free text. Only the first 1,000 characters are kept.                                                                                             |
| `task`         | `true` makes a task for the project's owner on the due date, as the Remind box does in tiny+. It's done when the team moves on from `preparing`. |
| `tender_teams` | How many teams are bidding in all, saved with the team. See [How many teams are bidding](#how-many-teams-are-bidding).                           |

```bash
curl -X POST "https://api.tiny.plus/v2/bid_teams" \
  -H "Authorization: Bearer {{user_access_token}}" \
  -H "Content-Type: application/json" \
  -d '{
        "project_id": 195414,
        "company_id": 164567,
        "fee": 120000,
        "chance": 20,
        "due_date": "2026-10-24",
        "note": "Their structural engineer asked for our health-sector references.",
        "task": true
      }'
```

The answer is the new team, as [One team](#one-team) returns it. A project that isn't a proposal can't take a team that's still in the running: that answers `409`.

## Change a team

<mark style="color:orange;">`PATCH`</mark> `https://api.tiny.plus/v2/bid_teams/{{id}}`

Send the `result`, or any of the fields [Add a team](#add-a-team) takes but `project_id` and `tender_teams`. A team can't move to another project. A new `fee` without `fee_currency` keeps the team's currency, and `fee_currency` needs a `fee` with it. `display_order` sets the team's place in the list. `task` `false` drops an open due-date task; without it, an open task follows a new due date.

```bash
curl -X PATCH "https://api.tiny.plus/v2/bid_teams/{{id}}" \
  -H "Authorization: Bearer {{user_access_token}}" \
  -H "Content-Type: application/json" \
  -d '{
        "result": "shortlisted",
        "chance": 35
      }'
```

The answer is the team, as [One team](#one-team) returns it, with the project as it is after the change. Everything is checked before anything is saved, and the result is set after the other fields, so a team that wins does so at the fee sent with it.

## Results

| `result`       | In tiny+     | In the running |
| -------------- | ------------ | -------------- |
| `preparing`    | Preparing    | Yes            |
| `in_bid`       | In the bid   | Yes            |
| `shortlisted`  | Shortlisted  | Yes            |
| `won`          | Won          | No             |
| `not_selected` | Not selected | No             |
| `not_included` | Not included | No             |
| `withdrew`     | Withdrew     | No             |

A result moves the project with it:

* **A win wins the project**, at the winning team's fee, with its lead firm as the client and its contact, if it has one, as the primary contact. The project's earlier client stays linked to it as its end client. The other teams in a bid are marked `not_selected`, and any still being prepared `withdrew`.
* **The last team out closes the project.** It's lost, or cancelled when the firm withdrew from every team, and the reason is added to its Feedback: "Our teams were not selected", "Not included in a team" or "Withdrew from every team". `closed_by_teams` is then `true`.
* **A closed project can't take a team back into the running.** That answers `409`. Reopen the project first, with [`PATCH /v2/projects/{id}`](https://docs.tiny.plus/api/endpoints/projects.md#status-and-phases) back to a proposal status or phase. Reopening puts back what the win or close changed: the teams' results, the client, the primary contact and the Feedback.

Moving a project by hand settles its teams the same way. Won makes the only team still in the running the winner; with more than one, the teams wait until one of them is marked `won`. Lost marks the teams in a bid `not_selected` and the rest `withdrew`. Cancelled and on hold leave them as they are.

## How many teams are bidding

<mark style="color:orange;">`PATCH`</mark> `https://api.tiny.plus/v2/bid_teams?project_id={{project_id}}`

`tender_teams` is how many teams are bidding for the project in all, whether the firm is on them or not: from `1` to `99`, or `null` when it isn't known. A team without a chance of its own counts for 1 in that many.

```bash
curl -X PATCH "https://api.tiny.plus/v2/bid_teams?project_id={{project_id}}" \
  -H "Authorization: Bearer {{user_access_token}}" \
  -H "Content-Type: application/json" \
  -d '{
        "tender_teams": 4
      }'
```

The answer is the project's teams, as [The teams on a project](#the-teams-on-a-project) returns them.

## Remove a team

<mark style="color:red;">`DELETE`</mark> `https://api.tiny.plus/v2/bid_teams/{{id}}`

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

```json
{
    "results": true,
    "project": {
        "id": 195414,
        "name": "Tasman Health new wing",
        "record_status": "proposal",
        "record_phase": 195,
        "record_status_display": "Long Term",
        "open": true,
        "probability": 40,
        "fee_value": "105000.00",
        "fee_from_stages": false,
        "proposal_due_date": "2026-11-07",
        "client": {
            "id": 164564,
            "name": "Tasman Health"
        },
        "tender_teams": 5,
        "default_chance": 20,
        "live_teams": 2,
        "chance_total": 40,
        "closed_by_teams": false,
        "record_url": "https://crm.tiny.plus/project/195414"
    }
}
```

`project` is the project as it is now. A team that's out of the running can stay, so the lead firm's numbers keep its result. Remove a team that was added by mistake.

## The fee and probability

While a project is a proposal with a team in the running:

* its `probability` is the chances of the teams in the running added up, at most 100, since only one of them can win;
* its `fee_value` is their fees averaged by chance, so the fee times the probability is the fee to expect;
* its `proposal_due_date` is the earliest due date among the teams still being prepared.

A [`PATCH /v2/projects/{id}`](https://docs.tiny.plus/api/endpoints/projects.md) that sends `fee_value` or `probability` for such a project leaves them as they are, and still answers `{"results": true}`. Once no team is in the running, they can be set again. Where the project's stages set its fee, they keep doing so, and only the probability comes from the teams.

## Errors

| Status | When                                                                                                                                                                                                                                                                                                                                |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Something in the request is wrong: `{"error": "A due date is written as YYYY-MM-DD."}`                                                                                                                                                                                                                                              |
| `403`  | The account doesn't have bid teams, or the token's user may not do it: `{"error": "Only someone who can edit the project's fee can set a team's fee or chance."}`. Also a [read-only token](https://docs.tiny.plus/api/concepts/permissions.md#read-only-tokens) trying to change anything: `{"error": "This token is read-only."}` |
| `404`  | There is no such project, team or company, or the token's user can't open it: `{"error": "That project could not be found."}`                                                                                                                                                                                                       |
| `409`  | The project's state rules it out: `{"error": "This project is closed. Reopen it to put a team back in the running."}`. Also a fee for a team on a project whose stages set its fee.                                                                                                                                                 |
