> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getaptly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Forms

> Embeddable external forms with location search for third-party websites.

Handles external embeddable forms — dynamic forms that can be embedded in third-party websites. These forms collect lead or inquiry data and can search for available property locations.

All endpoints are public (no auth required).

## GET `/forms/{formId}/{cardId}/{boardId}`

Retrieve the configuration and field definitions for an embeddable form.

<ParamField path="formId" type="string" required>
  The form definition ID.
</ParamField>

<ParamField path="cardId" type="string" required>
  The card context ID (integration-specific, e.g., a CRM card ID).
</ParamField>

<ParamField path="boardId" type="string" required>
  The board context ID (integration-specific, e.g., a CRM board ID).
</ParamField>

**Response**

```json theme={null}
{
  "_id": "form_abc123",
  "title": "Schedule a Tour",
  "fields": [
    {
      "uuid": "f_001",
      "type": "string",
      "label": "Full Name",
      "placeholder": "Jane Doe",
      "required": true
    },
    {
      "uuid": "f_002",
      "type": "email",
      "label": "Email Address",
      "required": true
    },
    {
      "uuid": "f_005",
      "type": "select",
      "label": "Bedrooms",
      "options": ["Studio", "1BR", "2BR", "3BR+"],
      "required": false
    }
  ],
  "submitLabel": "Request a Tour",
  "companyId": "org_abc123",
  "locationId": "loc_xyz789"
}
```

**Field `type` values**

| Value        | Description                      |
| ------------ | -------------------------------- |
| `"string"`   | Single-line text input           |
| `"email"`    | Email address input              |
| `"phone"`    | Phone number input               |
| `"date"`     | Date picker                      |
| `"select"`   | Dropdown with predefined options |
| `"boolean"`  | Yes/No toggle                    |
| `"money"`    | Currency amount input            |
| `"textarea"` | Multi-line text area             |

***

## POST `/forms/submit`

Submit a completed form.

**Request body**

```json theme={null}
{
  "formId": "form_abc123",
  "cardId": "card_001",
  "boardId": "board_001",
  "data": {
    "f_001": "Jane Doe",
    "f_002": "jane@example.com",
    "f_004": "2026-04-01",
    "f_005": "2BR"
  }
}
```

<ParamField body="formId" type="string" required>
  Form definition ID.
</ParamField>

<ParamField body="cardId" type="string" required>
  CRM card ID.
</ParamField>

<ParamField body="boardId" type="string" required>
  CRM board ID.
</ParamField>

<ParamField body="data" type="object" required>
  Key-value pairs of field UUID → user-entered value.
</ParamField>

**Response**

```json theme={null}
{
  "status": true,
  "message": "Thank you! We'll be in touch soon."
}
```

***

## POST `/forms/searchLocations`

Search for available property locations to populate a location picker in embeddable forms.

**Request body**

```json theme={null}
{
  "query": "Austin",
  "companyId": "org_abc123",
  "bedCount": 2,
  "maxRent": 200000
}
```

<ParamField body="query" type="string">
  Text search against location name or address.
</ParamField>

<ParamField body="companyId" type="string" required>
  Organization ID to search within.
</ParamField>

<ParamField body="bedCount" type="number">
  Filter by number of bedrooms.
</ParamField>

<ParamField body="maxRent" type="number">
  Maximum rent in cents (e.g., `200000` = \$2,000).
</ParamField>

**Response**

```json theme={null}
{
  "locations": [
    {
      "_id": "loc_xyz789",
      "name": "The Residences at Oak Creek - Unit 204",
      "address": { "formattedAddress": "123 Oak St, Austin TX 78701" },
      "bedCount": 2,
      "bathCount": 1,
      "squareFeet": 950,
      "marketRent": "$1,500",
      "marketRentValue": 150000,
      "coverPhoto": ["https://cdn.example.com/photos/cover.jpg"]
    }
  ]
}
```

<Note>
  Called in embeddable forms that let users select a specific unit before submitting a tour request or inquiry.
</Note>