API Introduction

The TIDY API is a REST API that lets you integrate property cleaning and maintenance management into your applications. Use it to automate job scheduling, manage properties, work with service professionals, and more.

What is the TIDY API?

The TIDY API lets you do many things you can do via the tidy.com website, including:

Requesting Jobs
Adding Pros you manage
Viewing Job Statuses
Updating the To-Do list for a job
Managing Guest Reservations for your Addresses
Managing properties and access instructions

The TIDY API is a REST API that uses standard HTTP response codes, authentication, and verbs. In principle, any feature available online could be made available through the TIDY API.

Base URL

All API requests should be made to:

https://api.tidy.com/v1

Making Your First Request

Here's an example of making an API call to retrieve your addresses:

Make sure you have your API key ready. See the Authentication guide for how to generate one.

Example Request (cURL)

curl https://api.tidy.com/v1/addresses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Request (JavaScript)

const response = await fetch('https://api.tidy.com/v1/addresses', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

Example Request (Python)

import requests

url = 'https://api.tidy.com/v1/addresses'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers)
data = response.json()
print(data)

Example Response

{
  "addresses": [
    {
      "id": 12345,
      "street": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "nickname": "Downtown Property",
      "bedrooms": 2,
      "bathrooms": 2
    }
  ]
}

Basic Architecture

Understanding TIDY's data model will help you use the API effectively:

Customers - Your account, with unique API Keys. Can have many Addresses.
Addresses - Physical locations for requested services. Each can have many Jobs, Pros, or To-Do Lists.
Jobs - Requested cleaning or maintenance work for an Address. Jobs are assigned to Pros and can have associated To-Do Lists.
Pros - Service professionals who perform the work.
To-Do Lists - Checklists that define what should be done for a job.
Reservations - Guest check-in/check-out information that can trigger automatic job scheduling.

Common Patterns

Pagination

List endpoints support pagination using limit and offset query parameters:

# Get first 20 jobs
GET /jobs?limit=20&offset=0

# Get next 20 jobs
GET /jobs?limit=20&offset=20

Filtering

Many endpoints support filtering. For example, filter jobs by address or status:

# Get all jobs for a specific address
GET /jobs?address_id=12345

# Get only completed jobs
GET /jobs?status=completed

Developer / API Support

We offer free API support for developers. To get that, you must:

Have an account (it's free)
Make sure you have "developer options" enabled (tap the developer tab to enable this)
Make requests from the "Developers" section or "Concierge" section

Our goal is to make your lives easier, but by logging in it helps us ensure security & privacy.

Quick Start Guide

Most people get started with the following steps:

TIDY Concierge