TimeToSell Enterprise API

Integrate TimeToSell.AI's propensity modeling, risk quantification, and headless CRM playbooks natively into your application.

The TimeToSell.AI API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL: All API requests should be made to https://api.timetosell.ai/v1/

Authentication

The TimeToSell API uses Bearer Tokens to authenticate requests. You can view and manage your API keys in the Developer Portal.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas.

Authentication Header

Authorization: Bearer sk_live_abc123def456ghi789

Async Architecture & Webhooks

Because TimeToSell.AI runs complex Machine Learning models and aggregates data from over 10 distinct databases, generating a payload takes between 4 to 8 seconds.

To prevent timeouts and allow you to submit thousands of properties simultaneously, our API utilizes an Asynchronous Webhook Queue.

You POST a job: Submit an address and your webhook_url.
Instant 202 Accepted: We instantly return a job_id and close the connection.
We Process: Our background workers calculate the intelligence payload.
We POST back: Once finished, we POST the final JSON payload directly to your webhook_url.

Analyze a Property

Submit a property address to the queue for predictive analysis.

POST /v1/intelligence

Parameter	Type	Description
address	string required	The full US property address.
webhook_url	string required	The HTTPS URL on your server where we will POST the final analysis.

Request (cURL)

curl -X POST "https://api.timetosell.ai/v1/intelligence" \
  -H "Authorization: Bearer sk_live_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "141 Sandy Hollow Trl, County, CO",
    "webhook_url": "https://api.yourdomain.com/tts-callback"
  }'

Response (Instant)

{
  "status": "accepted",
  "message": "Property analysis queued successfully.",
  "job_id": "JOB-A1B2C3D4"
}

The Webhook Payload (By Scope)

When the job completes, we POST the data to your Webhook. The contents of this JSON payload are strictly determined by the Scopes assigned to your API Key.

1. Core Liquidity Scope (Default)

The foundation of the API. Delivers physical asset truth, propensity scores, and buyer targeting metrics.

Score Velocity (Deltas): Measures 30-day index momentum.
ToMLS Probability Curve: The temporal timeline to listing (e.g. <9 Months).
Buyer & Seller Archetypes: Behavioral profiles for both sides of the transaction.

Webhook POST Payload (Core)

{
  "status": "completed",
  "data": {
    "job_id": "JOB-A1B2C3D4",
    "property_id": "rxM9LpQ2",
    "address": "123 Main St, Denver, CO 80202",
    "physical_specs": {
      "beds": 4,
      "baths": 2.5,
      "sqft": 2400,
      "coordinates": { "lat": 39.7392, "lng": -104.9903 }
    },
    "predictive_metrics": {
      "timetosell_index": 85,
      "index_30d_delta": "+15",
      "prediction_confidence_score": 92,
      "urgency_window": "<9 Months",
      "seller_profile": "Senior Downsizer"
    },
    "buyer_metrics": {
      "target_archetype": "Luxury Trade-Up",
      "financial_capacity": 85,
      "likely_loan_type": "CONVENTIONAL"
    }
  }
}

2. Risk & Quant Scope (+ risk)

Built for Institutional Capital and iBuyers. Delivers quantitative risk assessments based on geospatial intersections and debt-to-equity estimations.

Added to Payload

    "financial_metrics": {
      "valuation_band": "$480,000 - $520,000",
      "estimated_arbitrage_margin": "18.5%"
    },
    "risk_metrics": {
      "environmental_risk_score": 88,
      "financial_stress_score": 42,
      "micro_market_distress_trend": "Stable"
    }

3. Identity Enrichment (+ enrich)

Appends TCPA/DNC compliant contact details and predicts the optimal outreach channel based on demographic variables.

Added to Payload

    "contact_data": {
      "name": "John Doe",
      "phone": "(303) ***-1234",
      "email": "jo***@gmail.com",
      "contactability": {
        "dnc_flag": false,
        "optimal_channel": "Direct Mail"
      }
    }

4. CRM Playbooks Scope (+ playbooks)

Routes the data matrix through the TimeToSell AI Gateway. Generates headless, ready-to-send JSON workflows to automate agent engagement directly inside your CRM.

Added to Payload

    "crm_playbook": {
      "executive_summary": "High propensity to sell detected. Urgent disposition required.",
      "next_best_action": "TRIGGER_NURTURE_SEQUENCE",
      "ready_to_send_scripts": {
        "outreach_sms": "Hi John, noticed market shifts in your area. Have 5 mins?",
        "outreach_email_subject": "Market Update regarding your property"
      }
    }

Errors & Billing

TimeToSell uses conventional HTTP response codes to indicate the success or failure of an API request.

Code	Description
`202`	Accepted - The address was valid and added to the processing queue.
`400`	Bad Request - Missing required parameters (e.g., no webhook_url provided).
`401`	Unauthorized - No valid Bearer token provided in headers.
`402`	Payment Required - The wallet associated with your API key has insufficient funds to cover the scopes requested. You can auto-recharge your wallet in the Billing Dashboard.
`403`	Forbidden - The API key is deactivated or restricted.
`500`	Server Error - An issue occurred on our end. You are not billed for 500 errors.