Skip to content

Getting Started

This guide covers installation, configuration, and your first API calls with PyPropertyMe.

Installation

# Basic installation
uv add pypropertyme

# With CLI support
uv add pypropertyme[cli]

# With Airtable sync
uv add pypropertyme[airtable]

# With MongoDB sync
uv add pypropertyme[mongodb]

# All extras
uv add pypropertyme[cli,airtable,mongodb]

Configuration

Environment Variables

Create a .env file in your project root with your PropertyMe API credentials:

PROPERTYME_CLIENT_ID=your_client_id_here
PROPERTYME_CLIENT_SECRET=your_client_secret_here
PROPERTYME_REDIRECT_URI=http://localhost:65385/home/callback
PROPERTYME_SCOPES=["activity:read", "communication:read", "contact:read", "property:read", "transaction:read", "offline_access"]
Variable Required Description
PROPERTYME_CLIENT_ID Yes OAuth client ID from PropertyMe
PROPERTYME_CLIENT_SECRET Yes OAuth client secret
PROPERTYME_REDIRECT_URI No Callback URL (default shown above)
PROPERTYME_SCOPES No JSON array of OAuth scopes

Getting Credentials

Obtain your client ID and secret from the PropertyMe developer portal.

Authentication

Using the CLI

The simplest way to authenticate is using the CLI:

pypropertyme auth

This will:

  1. Start a local web server for the OAuth callback
  2. Open your browser to PropertyMe's login page
  3. After you authorize, exchange the code for tokens
  4. Store tokens securely in ~/.pypropertyme/tokens.json

OAuth 2.0 Flow

PyPropertyMe uses OAuth 2.0 with the authorization code flow:

sequenceDiagram
    participant User
    participant CLI
    participant Browser
    participant PropertyMe

    User->>CLI: pypropertyme auth
    CLI->>CLI: Start local callback server
    CLI->>Browser: Open authorization URL
    Browser->>PropertyMe: User logs in
    PropertyMe->>Browser: Redirect with auth code
    Browser->>CLI: Callback with code
    CLI->>PropertyMe: Exchange code for tokens
    PropertyMe->>CLI: Access + refresh tokens
    CLI->>CLI: Save to ~/.pypropertyme/tokens.json

Token Management

Tokens are automatically managed:

  • Access tokens expire after a short period
  • Refresh tokens are used to obtain new access tokens
  • The client handles token refresh transparently

First API Call

Using the CLI

After authenticating, you can immediately start fetching data:

# List all contacts
pypropertyme contacts

# Get a specific property
pypropertyme properties --id <property-id>

# Save to file
pypropertyme contacts -o contacts.json

Using Python

import asyncio
import json
from pathlib import Path
from pypropertyme.client import Client

async def main():
    # Load tokens from CLI authentication
    token_path = Path.home() / ".pypropertyme" / "tokens.json"
    token = json.loads(token_path.read_text())

    # Create client
    client = Client.get_client(token)

    # Fetch contacts
    contacts = await client.contacts.all()
    print(f"Found {len(contacts)} contacts")

    # Fetch properties
    properties = await client.properties.all()
    print(f"Found {len(properties)} properties")

    # Get a single contact with full details
    if contacts:
        contact_detail = await client.contacts.get(contacts[0].id)
        print(f"First contact: {contact_detail.contact.name_text}")

asyncio.run(main())

Next Steps