> ## 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.

# Aptly Portal API

> HTTP API for the Aptly rental application screening portal.

## Environments

The base URL for all API calls is:

```
https://app.getaptly.com/api/portal
```

All endpoint paths are relative to it.

## Request & Response Format

| Method             | Content-Type                    | Body       |
| ------------------ | ------------------------------- | ---------- |
| GET                | `application/json`              | none       |
| POST (JSON)        | `application/json`              | JSON       |
| POST (file upload) | *(omitted, multipart auto-set)* | `FormData` |
| DELETE             | `application/json`              | none       |

All responses are JSON. On success the HTTP status is `2xx`. On failure:

```json theme={null}
{ "reason": "human-readable error string" }
```

## Error responses

All errors return a JSON body with a `reason` field:

```json theme={null}
{ "reason": "human-readable error string" }
```

| Reason                                   | Status | Description                                                    |
| ---------------------------------------- | ------ | -------------------------------------------------------------- |
| `"jwt expired"`                          | 401    | Token has expired — re-authenticate via the verification flow  |
| `"Unauthorized"`                         | 401    | Token is missing or invalid                                    |
| `"Not found"`                            | 404    | The requested resource does not exist                          |
| `"Invalid orgId"`                        | 400    | The organization ID is missing or does not match any known org |
| `"Form not found"`                       | 404    | The form ID does not exist or is not active for this org       |
| `"Location not found"`                   | 404    | The property or location ID does not exist within this org     |
| `"Verification code invalid or expired"` | 400    | The submitted code was incorrect, already used, or has expired |

## Multi-tenancy

Every organization has a unique identifier that scopes all API calls. This ID appears in different fields depending on the endpoint:

| Name        | Where it appears                                     |
| ----------- | ---------------------------------------------------- |
| `orgId`     | Query parameters on most Portal API endpoints        |
| `companyId` | Returned in company config responses                 |
| `contextId` | Used internally in some form and knowledge endpoints |

These all refer to the same organization. When an endpoint asks for `orgId`, use your organization's ID regardless of what it is called elsewhere. If you are unsure of your `orgId`, call the [Load company-level config](/portal/api-context) endpoint — it is returned in the response.

## Common Data Types

<AccordionGroup>
  <Accordion title="Address">
    ```json theme={null}
    {
      "formattedAddress": "123 Main St, Austin TX 78701",
      "state": "TX",
      "countryName": "United States"
    }
    ```
  </Accordion>
</AccordionGroup>

## Public API

<CardGroup cols={2}>
  <Card title="Context & Locations" icon="building" href="/api-context">
    Company/org config, property listings, location search, nearby schools
  </Card>

  <Card title="Knowledge Base" icon="book-open" href="/api-knowledge">
    Retrieve help/knowledge documents
  </Card>

  <Card title="Forms" icon="rectangle-list" href="/api-forms">
    Embeddable external forms with location search
  </Card>
</CardGroup>