Surveys API

Trigger automated rent surveys and monitor survey progress programmatically. Build custom survey automation workflows and integrate with your property management systems.

POST

/pricewatch/surveys

Trigger a new automated rent survey for a community. The survey will collect pricing data, discover comparable communities, and enrich property information using AI agents.

How to Use This Endpoint

Business Context: Automate rent surveys to run on a schedule (weekly, monthly, quarterly) without manual intervention. Trigger surveys immediately after significant market events, competitor renovations, or when preparing for lease renewals and rate decisions.

Common Scenario: Your revenue management system triggers a PriceWatch survey every Monday morning for all active properties. The surveys run overnight, and by Tuesday your pricing team has fresh comp data showing that three competitors dropped rents last week—prompting a strategic decision to hold pricing or offer concessions.

Required Scope

pricewatch:write

Request Body

Field	Type	Required	Description
community_id	uuid	✓	Community ID to survey
include_enrichment	boolean	No	Collect amenities and images (default: true)
include_comparables	boolean	No	Discover comparable communities (default: true)
radius_miles	number	No	Search radius for comps (default: 3)

Example Request

cURL

curl -X POST "https://api.aryna.ai/v1/pricewatch/surveys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "community_id": "550e8400-e29b-41d4-a716-446655440000",
    "include_enrichment": true,
    "include_comparables": true,
    "radius_miles": 3
  }'

Example Response (202 Accepted)

JSON

{
  "success": true,
  "survey_id": "660e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "message": "Survey initiated for Sunset Apartments",
  "estimated_completion_minutes": 15
}

GET

/pricewatch/surveys

List surveys with filtering and pagination. Monitor survey history and track survey completion rates.

Required Scope

pricewatch:read

Query Parameters

Parameter	Type	Required	Description
community_id	uuid	No	Filter by community
status	string	No	Filter by status (queued, processing, completed, failed)
start_date	date	No	Filter by created date (ISO format)
end_date	date	No	Filter by created date (ISO format)
limit	integer	No	Results per page (max 100, default 50)
offset	integer	No	Pagination offset (default 0)

Example Request

cURL

curl "https://api.aryna.ai/v1/pricewatch/surveys?status=completed&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

JSON

{
  "surveys": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "community_id": "550e8400-e29b-41d4-a716-446655440000",
      "community_name": "Sunset Apartments",
      "status": "completed",
      "created_at": "2024-11-20T10:00:00Z",
      "completed_at": "2024-11-20T10:15:00Z",
      "comp_count": 8,
      "floor_plan_count": 12
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

GET

/pricewatch/surveys/:id

Get detailed survey status with job breakdown by agent. Monitor survey progress in real-time and track individual agent completion.

Required Scope

pricewatch:read

Path Parameters

Parameter	Type	Required	Description
id	uuid	✓	Survey ID

Example Request

cURL

curl "https://api.aryna.ai/v1/pricewatch/surveys/660e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

JSON

{
  "survey_id": "660e8400-e29b-41d4-a716-446655440000",
  "community_id": "550e8400-e29b-41d4-a716-446655440000",
  "community_name": "Sunset Apartments",
  "status": "processing",
  "created_at": "2024-11-20T10:00:00Z",
  "completed_at": null,
  "jobs": {
    "agent1_comp_discovery": {
      "job_id": "770e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "comps_found": 8,
      "created_at": "2024-11-20T10:00:00Z",
      "completed_at": "2024-11-20T10:02:00Z",
      "error_message": null,
      "retry_count": 0
    },
    "agent2_pricing": {
      "subject": {
        "job_id": "880e8400-e29b-41d4-a716-446655440000",
        "status": "completed",
        "created_at": "2024-11-20T10:02:00Z",
        "completed_at": "2024-11-20T10:05:00Z",
        "error_message": null,
        "retry_count": 0
      },
      "comps": [
        {
          "job_id": "990e8400-e29b-41d4-a716-446655440000",
          "comp_id": "aa0e8400-e29b-41d4-a716-446655440000",
          "status": "completed",
          "created_at": "2024-11-20T10:05:00Z",
          "completed_at": "2024-11-20T10:08:00Z",
          "error_message": null,
          "retry_count": 0
        }
      ]
    },
    "agent3_enrichment": {
      "job_id": "bb0e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "created_at": "2024-11-20T10:00:00Z",
      "completed_at": "2024-11-20T10:03:00Z",
      "error_message": null,
      "retry_count": 0
    },
    "agent4_positioning": {
      "job_id": "cc0e8400-e29b-41d4-a716-446655440000",
      "status": "pending",
      "created_at": null,
      "completed_at": null,
      "error_message": null,
      "retry_count": 0
    }
  },
  "estimated_completion": "2024-11-20T10:15:00Z"
}

Try it in the Interactive Docs

Test these endpoints directly in your browser with our interactive OpenAPI documentation.

Open Interactive API Docs