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

# Enquiries

Enquiries live at `/v2/enquiries`. They support every request on the [Records](https://docs.tiny.plus/api/endpoints/records.md) page: list, get, history, create, update, delete and search. On top of those, an enquiry can be passed on, marked as replied to, converted, closed and released, as it can in tiny+.

To capture enquiries from your website, you may not need the API at all: see [Capturing website enquiries](https://docs.tiny.plus/api/getting-access/javascript-token.md).

[`/me`](https://docs.tiny.plus/api/endpoints/me.md) lists `enquiries` in `api_features` where the server has everything on this page.

## Creating an enquiry

```bash
curl -X POST "https://api.tiny.plus/v2/enquiries" \
  -H "Authorization: Bearer {{user_access_token}}" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "New aged care facility",
        "description": "Asked about a 120-bed facility in Auchenflower.",
        "contact_name": "Andrew Xavier",
        "contact_company": "Xavier Developers",
        "contact_email": "andrew@example.com",
        "contact_phone": "0400 000 000"
      }'
```

```javascript
{
    "id": "161082"
}
```

* A new enquiry's `record_status` is `open`, or the first phase of `open` on accounts that use phases.
* **Who gets it.** Send `assigned_user` to name its owner. Leave it out and the account's rule decides, as it does for a web form: the Inbox (nobody yet), one person, or each of a group in turn. An enquiry in the Inbox has no `assigned_user`.
* **Who it is from.** When exactly one contact has the `contact_email` you sent, the enquiry is linked to that contact and their company. A company is also linked when exactly one has that name. Nothing is created.
* **Sent twice.** Send your own reference as `remote_id`. A second create with a `remote_id` the account already has answers with the first enquiry's id and changes nothing.
* If you don't send a `followup_date`, it's set to two business days after the enquiry is created, counting Monday to Friday. Public holidays aren't skipped.
* The enquiry's `source` is `api`, with your client's name in `source_detail`. What you sent is kept as it arrived in `received`. These three are set by tiny+ and can't be written.

## The person and company

`contact_name` and `contact_company` hold either text or a record id:

* **Text**, such as `"Andrew Xavier"`, is stored as it is, unless it matches as described above.
* **The id of an existing contact or company** links the enquiry to that record.

Reads return what's stored: the text, or the id.

## What a read adds

Every enquiry read carries an `enquiry` object, worked out by tiny+:

```javascript
"enquiry": {
    "source_label": "Web form: Contact us",
    "held": false,
    "reply_due": "2026-11-17 23:00:00",
    "first_reply": null,
    "reply": "waiting",
    "close_reason": null,
    "outcome": null,
    "summary": "Wants a feasibility study for a 120-bed aged care facility in Auchenflower.",
    "suspect": false,
    "suspect_why": null,
    "draft_reply": "Hi Andrew,\n\nThanks for getting in touch about..."
}
```

| Key            | What it is                                                                                                                                                                                                                 |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source_label` | How it came in, in words. A web form is named where the account has more than one.                                                                                                                                         |
| `held`         | `true` while a doubtful submission waits for someone to release it. A held enquiry has no owner and no reply clock.                                                                                                        |
| `reply_due`    | When a first reply is due, in UTC, or `null` where the account sets no reply time or the enquiry predates it.                                                                                                              |
| `first_reply`  | When it got its first reply, in UTC, or `null`.                                                                                                                                                                            |
| `reply`        | `replied`; `waiting` or `late` on an open enquiry with no reply yet; `null` on a held or closed one.                                                                                                                       |
| `close_reason` | `{key, name}` on an enquiry closed with a reason, else `null`.                                                                                                                                                             |
| `outcome`      | What a convert made: `{kind, project, contact, company, at, by, by_name, can_undo}`, where `kind` is `project`, `contact` or `existing` and `can_undo` says whether this user can still undo it. Else `null`.              |
| `summary`      | The tiny+ AI engine's one line on what was asked, where the account has that switched on. Else `null`.                                                                                                                     |
| `suspect`      | `true` where the tiny+ AI engine found something in the enquiry it would not rely on (the web marks it **Check**). `summary` and `draft_reply` are then `null`: show a warning, and treat what the enquiry asks with care. |
| `suspect_why`  | Why, in a few words, or `null`.                                                                                                                                                                                            |
| `draft_reply`  | Its draft of a first reply. On a single read only, never in a list.                                                                                                                                                        |

## The Inbox

`GET /v2/enquiries?inbox=1` lists the enquiries nobody has yet, held ones among them. Add `record_status=open` for the Inbox as tiny+ shows it.

## Passing it on

`POST /v2/enquiries/{id}/assign` with `to`: `me`, `inbox`, or a team member's id. An optional `note` goes to the new owner. Anyone who can see an enquiry nobody has may take it; passing on someone's enquiry takes the right to edit it.

## Marking it as replied to

`POST /v2/enquiries/{id}/replied` stamps the first reply, which stops the reply clock. It answers `{"id": 161082, "stamped": true}`, or `"stamped": false` when the enquiry already had its reply. Moving an enquiry out of its first phase, converting it or closing it stamps it too.

## Converting

`GET /v2/enquiries/{id}/convert` says what a convert can choose from, as the sheet in tiny+ does: `becomes`, the outcomes; `person` and `company`, each with the `options` found and the usual `pick`; `carry`, what can cross to a project, and `carry_usual`; `name`; `starts`, where a project can start in the pipeline; `owner`; and `remind_days`.

`POST /v2/enquiries/{id}/convert` converts it:

| Key           | What it is                                                                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `becomes`     | `project` (a new one), `contact` (just the person) or `existing` (part of a project you have). Required.                                                     |
| `person`      | A contact's id, `new` to make one from the enquiry's details, or `none`.                                                                                     |
| `company`     | A company's id, `new`, or `none`.                                                                                                                            |
| `project`     | With `existing`: the project's id.                                                                                                                           |
| `name`        | With `project`: the new project's name. The enquiry's subject where left out.                                                                                |
| `starts`      | With `project`: a value from `starts.options`.                                                                                                               |
| `owner`       | With `project`: the team member who owns it.                                                                                                                 |
| `carry`       | With `project` or `existing`: what crosses, as a list or a comma list of `description`, `location`, `categories`, `notes`, `files`, `tasks` and `followers`. |
| `remind_days` | With `contact`: books a follow-up that many days ahead. One of `remind_days` from the GET; `0` for none.                                                     |

The answer names what was made: `kind`, `project`, `contact`, `company`, `made` (which of them were created) and `url`. The enquiry closes in the account's first closed phase. A second convert answers `409`.

`POST /v2/enquiries/{id}/undo` takes a convert back, for the person who made it, within an hour: the enquiry reopens and what the convert created is removed. After that, or for anyone else, it answers `409` or `403`.

## Closing

`GET /v2/enquiries/{id}/close` lists what a close can choose from: `reasons` and `phases`, each a list of `{value, label}`, and `remind_days`.

`POST /v2/enquiries/{id}/close` closes it without a project:

| Key            | What it is                                                                                               |
| -------------- | -------------------------------------------------------------------------------------------------------- |
| `reason`       | A reason's `value`. Required.                                                                            |
| `phase`        | A closed phase's `value`. The first where left out.                                                      |
| `note`         | Why, in words. It is posted on the enquiry.                                                              |
| `keep_contact` | `true` saves the person as a contact.                                                                    |
| `remind_days`  | Books a follow-up that many days ahead.                                                                  |
| `duplicate_of` | With the reason `duplicate`: the enquiry it repeats. The two are linked, and files and tasks move to it. |

Setting `record_status` to a closed phase with `PATCH` still closes an enquiry, with no reason recorded.

## Held enquiries

`POST /v2/enquiries/{id}/release` lets a held enquiry through: it goes to whoever the account's rule says and its reply clock starts. Send `"op": "spam"` instead to close it as spam.

## The draft reply

`POST /v2/enquiries/{id}/draft` has the tiny+ AI engine read the enquiry again and write a new summary and draft reply. It answers `{"id", "summary", "has_reply"}`; read the enquiry for the draft. It answers `409` where the account hasn't switched the reading on, the enquiry is confidential or empty, or the day's allowance is used.

## Fields

| Field             | Label in tiny+  | Type              | Notes                                                                                                               | Editable |
| ----------------- | --------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------- | -------- |
| `assigned_user`   | Assigned To     | Team member id    | A team member's id.                                                                                                 | Yes      |
| `contact_company` | Contact Company | Text or record id | Their company: text, or an existing company's id. See [The person and company](#the-person-and-company).            | Yes      |
| `contact_email`   | Contact Email   | Email address     |                                                                                                                     | Yes      |
| `contact_name`    | Contact Name    | Text or record id | The person who asked: text, or an existing contact's id. See [The person and company](#the-person-and-company).     | Yes      |
| `contact_phone`   | Contact Phone   | Text              |                                                                                                                     | Yes      |
| `contact_role`    | Contact Role    | Text              |                                                                                                                     | Yes      |
| `description`     | Details         | Text              |                                                                                                                     | Yes      |
| `followup_date`   | Follow-up by    | Date              | `YYYY-MM-DD`. Two business days after the enquiry is created, unless you send another.                              | Yes      |
| `location_id`     | Location        | Address           | An address. Reads return its id only.                                                                               | Yes      |
| `name`            | Subject         | Text              | Required. What the enquiry is about. Up to 200 characters.                                                          | Yes      |
| `notes`           | Notes           | Text              |                                                                                                                     | Yes      |
| `received`        | As received     | JSON              | What was sent, as it arrived, before anyone edited it. Set by tiny+.                                                | No       |
| `record_status`   | Current Status  | Option            | `open` unless you send another, or the first phase of `open` on accounts that use phases.                           | Yes      |
| `source`          | Source          | Option            | How it came in: `web_form`, `email`, `app` (added by hand), `api`, `import`, `other` or `unknown`. Set by tiny+.    | No       |
| `source_detail`   | Source detail   | Text              | More about the source: the API client's name, or the page a form was sent from. Set by tiny+. Up to 400 characters. | No       |
| `source_form`     | Web form        | Whole number      | The web form it came through, as that form's id. Set by tiny+.                                                      | No       |
