Projects & Prospects

┌──────────────────────────────────────────────────────────────────────┐
│                            PROJECT                                    │
│  (Real estate transaction — single asset or portfolio)                │
│                                                                       │
│  PROSPECTS (unified list via API)                                     │
│  ┌────────────────────────────────────────────────────────────────┐   │
│  │                                                                │   │
│  │  Added by you              Matched by Propstreet               │   │
│  │  ─────────────             ─────────────────────               │   │
│  │  • No teaser object        • teaser.deadlineUtc (response by)  │   │
│  │  • classification          • teaser.acceptedUtc (if accepted)  │   │
│  │  • tags from your network  • chat capability (when established)│   │
│  │                                                                │   │
│  │  All prospects share: classification, externalRefs, etag       │   │
│  └────────────────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────────────┘

HTTP/1.1 200 OK
ETag: W/"abc123"
Content-Type: application/json

{
  "id": "123",
  "name": "Stockholm Office Portfolio",
  "etag": "W/\"abc123\"",
...
}

curl -X PATCH "https://app.propstreet.com/api/v1/projects/123" \
  -H "If-Match: W/\"abc123\"" \
  -d '{"name": "Updated Name"}'

{
  "type": "urn:propstreet:error:precondition-failed",
  "title": "Precondition failed",
  "detail": "ETag mismatch - resource was modified"
}

curl "https://app.propstreet.com/api/v1/projects?page_size=100" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "123",
      "name": "Stockholm Office Portfolio",
      "asset": { "type": "portfolio", "propertyCount": 5 },
      "status": "open",
      "classification": "active",
      "teaser": {
        "stage": "published",
        "publishedUtc": "2026-01-14T09:00:00Z"
      },
      "mandate": "exclusive",
      "price": { "value": 150, "currency": "SEK", "scale": "millions" },
      "externalRefs": [{ "namespace": "hubspot", "id": "deal-123456" }],
      "createdUtc": "2026-01-15T10:00:00Z",
      "updatedUtc": "2026-01-15T10:00:00Z",
      "etag": "W/\"abc123\""
    }
  ],
  "page": {
    "nextCursor": "eyJ1IjoiMjAyNi0wMS0xNVQxMDowMDowMFoiLCJpIjoxMjN9",
    "pageSize": 100,
    "hasMore": true
  }
}

{ "type": "portfolio", "propertyCount": 5 }

{
  "stage": "communicated",
  "publishedUtc": "2026-01-10T10:00:00Z",
  "verifiedUtc": "2026-01-12T14:00:00Z",
  "communicatedUtc": "2026-01-15T09:00:00Z"
}

{ "value": 150, "currency": "SEK", "scale": "millions" }

{ "min": 100, "max": 200, "currency": "SEK", "scale": "millions" }

curl "https://app.propstreet.com/api/v1/projects/123" \
  -H "Authorization: Bearer $TOKEN"

curl -X POST "https://app.propstreet.com/api/v1/projects" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Stockholm Office Portfolio",
    "asset": { "type": "portfolio", "propertyCount": 5 },
    "mandate": "exclusive",
    "price": { "value": 150, "currency": "SEK", "scale": "millions" }
  }'

curl -X PATCH "https://app.propstreet.com/api/v1/projects/123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "If-Match: W/\"abc123\"" \
  -d '{
    "name": "Updated Project Name",
    "asset": { "type": "portfolio", "propertyCount": 3 }
  }'

curl -X DELETE "https://app.propstreet.com/api/v1/projects/123" \
  -H "Authorization: Bearer $TOKEN"

curl "https://app.propstreet.com/api/v1/projects/123/prospects?page_size=100" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "456",
      "projectId": "123",
      "contactId": "789",
      "companyId": "321",
      "interest": "interested",
      "stage": "teaser",
      "nextTask": {
        "id": "9012",
        "type": "call",
        "dueDateUtc": "2026-02-01T00:00:00Z",
        "assignee": { "id": "u-77", "name": "Anna Berg" },
        "overdue": false
      },
      "openTaskCount": 1,
      "classification": "interested",
      "capabilities": ["chat"],
      "tags": ["tier-1", "repeat-buyer"],
      "projectTags": ["Single tenant", "Follow up Q4"],
      "externalRefs": [{ "namespace": "salesforce", "id": "006XXXXXXXXXXXX" }],
      "teaser": {
        "acceptedUtc": "2026-01-20T14:30:00Z",
        "deadlineUtc": "2026-02-15T23:59:59Z"
      },
      "createdUtc": "2026-01-15T10:00:00Z",
      "updatedUtc": "2026-01-20T14:30:00Z",
      "etag": "W/\"def456\""
    }
  ],
  "page": {
    "nextCursor": "...",
    "pageSize": 100,
    "hasMore": false
  }
}

curl "https://app.propstreet.com/api/v1/projects/123/prospects/456" \
  -H "Authorization: Bearer $TOKEN"

# Add a contact
curl -X POST "https://app.propstreet.com/api/v1/projects/123/prospects" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"contactId": "789"}'

# Add a company
curl -X POST "https://app.propstreet.com/api/v1/projects/123/prospects" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"companyId": "456"}'

# Record your judgement (send null to clear it)
curl -X PATCH "https://app.propstreet.com/api/v1/projects/123/prospects/456" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "If-Match: W/\"def456\"" \
  -d '{"interest": "maybe"}'

# Correct the process stage, with the reason
curl -X PATCH "https://app.propstreet.com/api/v1/projects/123/prospects/456" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "If-Match: W/\"def456\"" \
  -d '{"stage": "data_room", "stageReason": "Access granted by mail"}'

# Legacy single-value classification (still accepted; prefer interest / stage)
curl -X PATCH "https://app.propstreet.com/api/v1/projects/123/prospects/456" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "If-Match: W/\"def456\"" \
  -d '{"classification": "bidder"}'

# Update external refs
curl -X PATCH "https://app.propstreet.com/api/v1/projects/123/prospects/456" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "If-Match: W/\"def456\"" \
  -d '{"externalRefs": [{"namespace": "salesforce", "id": "006XXXXXXXXXXXX"}]}'

# Replace the project-level tags (send [] to clear; the contact's own tags are untouched)
curl -X PATCH "https://app.propstreet.com/api/v1/projects/123/prospects/456" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "If-Match: W/\"def456\"" \
  -d '{"projectTags": ["Single tenant", "Follow up Q4"]}'

# Add a task (type: call | meeting | email; dueDate: "today", "tomorrow", "7d", "1w", or an ISO date — a past date is accepted and the task is already overdue)
curl -X POST "https://app.propstreet.com/api/v1/projects/123/prospects/456/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "call", "dueDate": "tomorrow", "assignee": "me", "note": "Follow up on the IM"}'

# Complete a task by its id (see "Task ids" below)
curl -X POST "https://app.propstreet.com/api/v1/projects/123/prospects/456/tasks/789/complete" \
  -H "Authorization: Bearer $TOKEN"

# Cancel a task, for example one created by mistake
curl -X POST "https://app.propstreet.com/api/v1/projects/123/prospects/456/tasks/789/cancel" \
  -H "Authorization: Bearer $TOKEN"

# Undo a completion: the task is open again
curl -X POST "https://app.propstreet.com/api/v1/projects/123/prospects/456/tasks/789/reopen" \
  -H "Authorization: Bearer $TOKEN"

curl -X DELETE "https://app.propstreet.com/api/v1/projects/123/prospects/456/stage-override" \
  -H "Authorization: Bearer $TOKEN"

curl -X DELETE "https://app.propstreet.com/api/v1/projects/123/prospects/456" \
  -H "Authorization: Bearer $TOKEN"

curl "https://app.propstreet.com/api/v1/network/contacts/789/projects?page_size=100" \
  -H "Authorization: Bearer $TOKEN"

curl "https://app.propstreet.com/api/v1/network/companies/321/projects?page_size=100" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "123",
      "prospectId": "456",
      "name": "Stockholm Office Portfolio",
      "status": "open",
      "classification": "active",
      "prospectClassification": "interested",
      "prospectCount": 12,
      "createdUtc": "2026-01-15T10:00:00Z",
      "updatedUtc": "2026-01-20T14:30:00Z",
      "etag": "W/\"abc123\""
    }
  ],
  "page": {
    "nextCursor": "eyJ1IjoiMjAyNi0wMS0xNVQxMDowMDowMFoiLCJpIjoxMjN9",
    "pageSize": 100,
    "hasMore": true
  }
}

{
  "externalRefs": [
    { "namespace": "hubspot", "id": "deal-123456" },
    { "namespace": "salesforce", "id": "006XXXXXXXXXXXX" }
  ]
}

curl -X POST "https://app.propstreet.com/api/v1/projects" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Stockholm Office Portfolio",
    "externalRefs": [
      { "namespace": "hubspot", "id": "deal-123456" }
    ]
  }'

curl -X PATCH "https://app.propstreet.com/api/v1/projects/123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalRefs": [
      { "namespace": "salesforce", "id": "006XXXXXXXXXXXX" },
      { "namespace": "pipedrive", "id": "12345" }
    ]
  }'

curl -X PATCH "https://app.propstreet.com/api/v1/projects/123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"externalRefs": []}'

# Find project by HubSpot deal ID
curl "https://app.propstreet.com/api/v1/projects/external/hubspot/deal-123456" \
  -H "Authorization: Bearer $TOKEN"

# Find prospect by Salesforce opportunity ID
curl "https://app.propstreet.com/api/v1/projects/123/prospects/external/salesforce/006XXXXXXXXXXXX" \
  -H "Authorization: Bearer $TOKEN"

class PropstreetCRMSync:
    def sync_from_crm(self, crm_deal):
        """Sync CRM deal to Propstreet, creating or updating as needed."""
        # Check if project already exists using CRM ID
        response = requests.get(
            f"{self.base_url}/projects/external/hubspot/{crm_deal.id}",
            headers=self.headers
        )

        if response.status_code == 200:
            # Update existing project
            project = response.json()
            requests.patch(
                f"{self.base_url}/projects/{project['id']}",
                headers=self.headers,
                json={"name": crm_deal.name}
            )
        elif response.status_code == 404:
            # Create new project with external ref
            requests.post(
                f"{self.base_url}/projects",
                headers=self.headers,
                json={
                    "name": crm_deal.name,
                    "externalRefs": [
                        {"namespace": "hubspot", "id": crm_deal.id}
                    ]
                }
            )

curl -X POST "https://app.propstreet.com/api/v1/projects/123/prospects:batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "contactId": "101" },
      { "contactId": "102", "externalRefs": [{ "namespace": "hubspot", "id": "deal-789" }] },
      { "companyId": "201" },
      { "contactId": "103" }
    ]
  }'

{
  "created": [
    { "id": "456", "contactId": "101" },
    {
      "id": "457",
      "contactId": "102",
      "externalRefs": [{ "namespace": "hubspot", "id": "deal-789" }]
    },
    { "id": "458", "companyId": "201" }
  ],
  "failed": [
    {
      "index": 3,
      "contactId": "103",
      "error": "duplicate",
      "message": "Contact already exists as prospect in this project"
    }
  ]
}

{
  "event": "project.updated",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "id": "123",
    "name": "Stockholm Office Portfolio",
    "asset": { "type": "portfolio", "propertyCount": 5 },
    "status": "open",
    "classification": "active",
    "teaser": {
      "stage": "communicated",
      "publishedUtc": "2026-01-10T10:00:00Z",
      "verifiedUtc": "2026-01-12T14:00:00Z",
      "communicatedUtc": "2026-01-15T09:00:00Z"
    },
    "changeOrigin": "<opaque>",
    "externalRefs": [{ "namespace": "hubspot", "id": "deal-123456" }],
    "changedFields": ["teaser.stage"]
  }
}

# Webhook subscription with external ref filter
curl -X POST "https://app.propstreet.com/api/v1/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-system.com/webhooks/propstreet",
    "events": ["project.updated", "prospect.updated"],
    "filter": {
      "externalRef.namespace": "hubspot"
    }
  }'

async function initialSync(token) {
  // 1. Fetch all projects
  let cursor = null;
  const projects = [];

  do {
    const url = new URL("https://app.propstreet.com/api/v1/projects");
    url.searchParams.set("page_size", "500");
    if (cursor) url.searchParams.set("cursor", cursor);

    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${token}` },
    });
    const { data, page } = await response.json();

    projects.push(...data);
    cursor = page.hasMore ? page.nextCursor : null;
  } while (cursor);

  // 2. Fetch prospects for each project
  for (const project of projects) {
    const prospects = await fetchAllProspects(token, project.id);
    await saveToDatabase(project, prospects);
  }

  return projects.length;
}

async function deltaSync(token, lastSyncTime) {
  const url = new URL("https://app.propstreet.com/api/v1/projects");
  url.searchParams.set("updated_since", lastSyncTime.toISOString());
  url.searchParams.set("include_deleted", "true");

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${token}` },
  });
  const { data } = await response.json();

  for (const project of data) {
    if (project.deletedUtc) {
      await markAsDeleted(project.id);
    } else {
      await upsertProject(project);
      // Also sync prospects for updated projects
      const prospects = await fetchAllProspects(
        token,
        project.id,
        lastSyncTime
      );
      await syncProspects(project.id, prospects);
    }
  }
}

# Get only prospects with chat enabled
curl "https://app.propstreet.com/api/v1/projects/123/prospects?capability=chat" \
  -H "Authorization: Bearer $TOKEN"

# Get the prospects you judged interested
curl "https://app.propstreet.com/api/v1/projects/123/prospects?interest=interested" \
  -H "Authorization: Bearer $TOKEN"

# Get the prospects in the Case Room you have not judged yet
curl "https://app.propstreet.com/api/v1/projects/123/prospects?stage=data_room&interest=none" \
  -H "Authorization: Bearer $TOKEN"

# Get prospects whose contact or company carries a network tag
curl "https://app.propstreet.com/api/v1/projects/123/prospects?tags=tier-1" \
  -H "Authorization: Bearer $TOKEN"

# Get prospects you labelled in this project (case-insensitive, any of the listed tags)
curl "https://app.propstreet.com/api/v1/projects/123/prospects?project_tags=Single%20tenant" \
  -H "Authorization: Bearer $TOKEN"

import requests
from datetime import datetime, timezone

class PropstreetSync:
    def __init__(self, token):
        self.base_url = "https://app.propstreet.com/api/v1"
        self.headers = {"Authorization": f"Bearer {token}"}

    def sync_projects_to_crm(self, last_sync: datetime):
        """Sync Propstreet projects to CRM deals."""
        params = {
            "updated_since": last_sync.isoformat(),
            "include_deleted": "true"
        }

        response = requests.get(
            f"{self.base_url}/projects",
            headers=self.headers,
            params=params
        )
        projects = response.json()["data"]

        for project in projects:
            if project.get("deletedUtc"):
                self.crm.archive_deal(project["id"])
            else:
                asset = project["asset"]
                self.crm.upsert_deal({
                    "external_id": project["id"],
                    "name": project["name"],
                    "stage": self.map_to_crm_stage(project),
                    "is_portfolio": asset["type"] == "portfolio",
                    "property_count": asset.get("propertyCount")
                })

                # Sync prospects as deal contacts
                self.sync_prospects(project["id"])

    def sync_prospects(self, project_id: str):
        """Sync prospects to CRM deal contacts."""
        response = requests.get(
            f"{self.base_url}/projects/{project_id}/prospects",
            headers=self.headers
        )
        prospects = response.json()["data"]

        for prospect in prospects:
            contact_id = prospect.get("contactId") or prospect.get("companyId")
            teaser = prospect.get("teaser")
            self.crm.link_contact_to_deal(
                deal_id=project_id,
                contact_id=contact_id,
                role=prospect.get("classification"),
                is_communicated=teaser is not None and teaser.get("acceptedUtc") is not None
            )

    def map_to_crm_stage(self, project: dict) -> str:
        """Map project fields to CRM pipeline stage.

        Uses teaser.stage for progress tracking since status is lifecycle only.
        """
        if project["status"] == "closed":
            return "Closed Won"

        teaser = project.get("teaser")
        teaser_stage = teaser.get("stage") if teaser else None
        return {
            None: "Qualification",
            "property_added": "Qualification",
            "drafting": "Qualification",
            "published": "Proposal",
            "verified": "Proposal",
            "communicated": "Negotiation"
        }.get(teaser_stage, "Qualification")