Deals API - Winnerr CRM

The Deals API provides comprehensive pipeline management functionality for real estate transactions, enabling agents to track deals from initial contact through closing with complete visibility and control.

Deal Object

Deal Properties

{
  "id": "deal_123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "org_123e4567-e89b-12d3-a456-426614174000",
  "title": "Miami Waterfront Condo Sale",
  "description": "Luxury 2BR/2BA oceanfront condo with panoramic views",
  "type": "SALE",
  "stage": "NEGOTIATION",
  "status": "ACTIVE",
  "amount": 750000,
  "commission": {
    "rate": 0.06,
    "amount": 45000,
    "split": 0.5
  },
  "contact": {
    "id": "contact_123",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com"
  },
  "property": {
    "id": "property_456",
    "address": "123 Ocean Drive, Miami Beach, FL 33139",
    "type": "CONDO",
    "bedrooms": 2,
    "bathrooms": 2,
    "squareFootage": 1200
  },
  "assignedTo": "agent_123e4567-e89b-12d3-a456-426614174000",
  "teamMembers": [
    {
      "userId": "user_456",
      "role": "LISTING_AGENT",
      "commissionSplit": 0.5
    },
    {
      "userId": "user_789",
      "role": "BUYER_AGENT",
      "commissionSplit": 0.5
    }
  ],
  "timeline": {
    "listingDate": "2024-01-01T00:00:00Z",
    "contractDate": "2024-01-15T00:00:00Z",
    "inspectionDate": "2024-01-22T00:00:00Z",
    "appraisalDate": "2024-01-25T00:00:00Z",
    "closingDate": "2024-02-15T00:00:00Z"
  },
  "documents": [
    {
      "id": "doc_123",
      "name": "Purchase Agreement",
      "type": "CONTRACT",
      "url": "https://storage.winnerr.com/documents/doc_123.pdf"
    }
  ],
  "tasks": [
    {
      "id": "task_123",
      "title": "Schedule inspection",
      "dueDate": "2024-01-20T00:00:00Z",
      "completed": false
    }
  ],
  "probability": 75,
  "source": "REFERRAL",
  "tags": ["luxury", "waterfront", "cash-buyer"],
  "notes": "Buyer is pre-approved for cash purchase",
  "createdAt": "2024-01-01T10:00:00Z",
  "updatedAt": "2024-01-15T14:30:00Z",
  "lastActivityAt": "2024-01-15T14:30:00Z"
}

Deal Types

Type	Description
`SALE`	Property sale transaction
`PURCHASE`	Property purchase transaction
`LEASE`	Property lease transaction
`RENTAL`	Property rental transaction

Deal Stages

Stage	Description
`LEAD`	Initial contact or inquiry
`QUALIFIED`	Qualified prospect
`APPOINTMENT`	Scheduled showing or meeting
`NEGOTIATION`	Active negotiation
`CONTRACT`	Under contract
`INSPECTION`	Inspection period
`APPRAISAL`	Appraisal in progress
`FINANCING`	Financing approval
`CLOSING`	Closing preparation
`CLOSED`	Deal closed successfully
`LOST`	Deal lost or cancelled

Deal Status

Status	Description
`ACTIVE`	Deal is active and progressing
`ON_HOLD`	Deal is temporarily paused
`CANCELLED`	Deal has been cancelled
`CLOSED`	Deal has been closed

Endpoints

List Deals

Retrieve a paginated list of deals with optional filtering and sorting.

curl -X GET "https://api.winnerr.com/v1/deals" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

const response = await fetch('https://api.winnerr.com/v1/deals', {
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

import requests

response = requests.get(
    'https://api.winnerr.com/v1/deals',
    headers={
        'Authorization': 'Bearer YOUR_JWT_TOKEN',
        'Content-Type': 'application/json'
    }
)

data = response.json()

Query Parameters:

Parameter	Type	Description
`limit`	integer	Number of deals to return (1-100, default: 25)
`cursor`	string	Pagination cursor for next page
`type`	string	Filter by deal type
`stage`	string	Filter by deal stage
`status`	string	Filter by deal status
`assignedTo`	string	Filter by assigned agent
`amount[gte]`	number	Filter by minimum deal amount
`amount[lte]`	number	Filter by maximum deal amount
`probability[gte]`	integer	Filter by minimum probability
`createdAt[gte]`	string	Filter by creation date (ISO 8601)
`closingDate[gte]`	string	Filter by closing date (ISO 8601)
`sort`	string	Sort order (e.g., “amount:desc,createdAt:desc”)
`include`	string	Include related data (e.g., “contact,property,documents”)

Response:

{
  "success": true,
  "data": [
    {
      "id": "deal_123",
      "title": "Miami Waterfront Condo Sale",
      "type": "SALE",
      "stage": "NEGOTIATION",
      "status": "ACTIVE",
      "amount": 750000,
      "probability": 75,
      "assignedTo": "agent_123",
      "closingDate": "2024-02-15T00:00:00Z",
      "createdAt": "2024-01-01T10:00:00Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "eyJpZCI6IjEyNCJ9",
    "total": 85,
    "limit": 25
  }
}

Get Deal

Retrieve a specific deal by ID.

curl -X GET "https://api.winnerr.com/v1/deals/deal_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

const response = await fetch('https://api.winnerr.com/v1/deals/deal_123', {
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  }
});

const deal = await response.json();

Path Parameters:

Parameter	Type	Description
`id`	string	Deal ID

Query Parameters:

Parameter	Type	Description
`include`	string	Include related data (e.g., “contact,property,documents,tasks,activities”)

Response:

{
  "success": true,
  "data": {
    "id": "deal_123",
    "title": "Miami Waterfront Condo Sale",
    "type": "SALE",
    "stage": "NEGOTIATION",
    "amount": 750000,
    "contact": {
      "id": "contact_123",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com"
    },
    "property": {
      "id": "property_456",
      "address": "123 Ocean Drive, Miami Beach, FL 33139",
      "type": "CONDO"
    },
    "tasks": [
      {
        "id": "task_123",
        "title": "Schedule inspection",
        "dueDate": "2024-01-20T00:00:00Z",
        "completed": false
      }
    ]
  }
}

Create Deal

Create a new deal in the pipeline.

curl -X POST "https://api.winnerr.com/v1/deals" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Downtown Loft Sale",
    "type": "SALE",
    "stage": "QUALIFIED",
    "amount": 450000,
    "contactId": "contact_456",
    "propertyId": "property_789",
    "timeline": {
      "closingDate": "2024-03-01T00:00:00Z"
    },
    "commission": {
      "rate": 0.06
    },
    "probability": 60
  }'

const response = await fetch('https://api.winnerr.com/v1/deals', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Downtown Loft Sale',
    type: 'SALE',
    stage: 'QUALIFIED',
    amount: 450000,
    contactId: 'contact_456',
    propertyId: 'property_789',
    timeline: {
      closingDate: '2024-03-01T00:00:00Z'
    },
    commission: {
      rate: 0.06
    },
    probability: 60
  })
});

const deal = await response.json();

Request Body:

Field	Type	Required	Description
`title`	string	Yes	Deal title
`type`	string	Yes	Deal type (SALE, PURCHASE, LEASE, RENTAL)
`stage`	string	No	Deal stage (default: LEAD)
`amount`	number	Yes	Deal amount
`contactId`	string	Yes	Associated contact ID
`propertyId`	string	No	Associated property ID
`description`	string	No	Deal description
`timeline`	object	No	Deal timeline dates
`commission`	object	No	Commission details
`probability`	integer	No	Deal probability (0-100)
`source`	string	No	Deal source
`tags`	array	No	Array of tags
`notes`	string	No	Additional notes

Response:

{
  "success": true,
  "data": {
    "id": "deal_456",
    "title": "Downtown Loft Sale",
    "type": "SALE",
    "stage": "QUALIFIED",
    "status": "ACTIVE",
    "amount": 450000,
    "probability": 60,
    "commission": {
      "rate": 0.06,
      "amount": 27000
    },
    "createdAt": "2024-01-15T16:00:00Z",
    "updatedAt": "2024-01-15T16:00:00Z"
  }
}

Update Deal

Update an existing deal’s information.

curl -X PUT "https://api.winnerr.com/v1/deals/deal_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stage": "CONTRACT",
    "amount": 740000,
    "probability": 90,
    "timeline": {
      "contractDate": "2024-01-15T00:00:00Z",
      "closingDate": "2024-02-10T00:00:00Z"
    }
  }'

const response = await fetch('https://api.winnerr.com/v1/deals/deal_123', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    stage: 'CONTRACT',
    amount: 740000,
    probability: 90,
    timeline: {
      contractDate: '2024-01-15T00:00:00Z',
      closingDate: '2024-02-10T00:00:00Z'
    }
  })
});

const deal = await response.json();

Path Parameters:

Parameter	Type	Description
`id`	string	Deal ID

Request Body: Same fields as create deal (all optional for updates) Response:

{
  "success": true,
  "data": {
    "id": "deal_123",
    "title": "Miami Waterfront Condo Sale",
    "stage": "CONTRACT",
    "amount": 740000,
    "probability": 90,
    "timeline": {
      "contractDate": "2024-01-15T00:00:00Z",
      "closingDate": "2024-02-10T00:00:00Z"
    },
    "updatedAt": "2024-01-15T17:30:00Z"
  }
}

Delete Deal

Delete a deal from the pipeline.

curl -X DELETE "https://api.winnerr.com/v1/deals/deal_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

const response = await fetch('https://api.winnerr.com/v1/deals/deal_123', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  }
});

Path Parameters:

Parameter	Type	Description
`id`	string	Deal ID

Response:

{
  "success": true,
  "message": "Deal deleted successfully"
}

Deal Tasks

List Deal Tasks

Retrieve tasks associated with a deal.

curl -X GET "https://api.winnerr.com/v1/deals/deal_123/tasks" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

const response = await fetch('https://api.winnerr.com/v1/deals/deal_123/tasks', {
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  }
});

const tasks = await response.json();

Response:

{
  "success": true,
  "data": [
    {
      "id": "task_123",
      "title": "Schedule inspection",
      "description": "Coordinate property inspection with buyer",
      "dueDate": "2024-01-20T00:00:00Z",
      "completed": false,
      "assignedTo": "agent_123",
      "priority": "HIGH",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ]
}

Create Deal Task

Add a new task to a deal.

curl -X POST "https://api.winnerr.com/v1/deals/deal_123/tasks" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Order appraisal",
    "description": "Contact appraiser for property valuation",
    "dueDate": "2024-01-25T00:00:00Z",
    "priority": "MEDIUM",
    "assignedTo": "agent_123"
  }'

const response = await fetch('https://api.winnerr.com/v1/deals/deal_123/tasks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Order appraisal',
    description: 'Contact appraiser for property valuation',
    dueDate: '2024-01-25T00:00:00Z',
    priority: 'MEDIUM',
    assignedTo: 'agent_123'
  })
});

const task = await response.json();

Deal Documents

List Deal Documents

Retrieve documents associated with a deal.

curl -X GET "https://api.winnerr.com/v1/deals/deal_123/documents" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

const response = await fetch('https://api.winnerr.com/v1/deals/deal_123/documents', {
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  }
});

const documents = await response.json();

Response:

{
  "success": true,
  "data": [
    {
      "id": "doc_123",
      "name": "Purchase Agreement",
      "type": "CONTRACT",
      "size": 245760,
      "mimeType": "application/pdf",
      "url": "https://storage.winnerr.com/documents/doc_123.pdf",
      "signedAt": "2024-01-15T14:30:00Z",
      "uploadedAt": "2024-01-15T14:00:00Z"
    }
  ]
}

Upload Deal Document

Upload a new document to a deal.

curl -X POST "https://api.winnerr.com/v1/deals/deal_123/documents" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "file=@purchase_agreement.pdf" \
  -F "name=Purchase Agreement" \
  -F "type=CONTRACT"

const formData = new FormData();
formData.append('file', file);
formData.append('name', 'Purchase Agreement');
formData.append('type', 'CONTRACT');

const response = await fetch('https://api.winnerr.com/v1/deals/deal_123/documents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  },
  body: formData
});

const document = await response.json();

Deal Activities

List Deal Activities

Retrieve activity history for a deal.

curl -X GET "https://api.winnerr.com/v1/deals/deal_123/activities" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

const response = await fetch('https://api.winnerr.com/v1/deals/deal_123/activities', {
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  }
});

const activities = await response.json();

Response:

{
  "success": true,
  "data": [
    {
      "id": "activity_123",
      "type": "STAGE_CHANGED",
      "description": "Deal stage changed from QUALIFIED to NEGOTIATION",
      "createdAt": "2024-01-15T14:20:00Z",
      "userId": "user_123",
      "metadata": {
        "previousStage": "QUALIFIED",
        "newStage": "NEGOTIATION"
      }
    }
  ]
}

Pipeline Management

Get Pipeline Overview

Retrieve pipeline statistics and stage breakdown.

curl -X GET "https://api.winnerr.com/v1/deals/pipeline" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

const response = await fetch('https://api.winnerr.com/v1/deals/pipeline', {
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  }
});

const pipeline = await response.json();

Response:

{
  "success": true,
  "data": {
    "totalValue": 5250000,
    "totalDeals": 28,
    "averageDealSize": 187500,
    "conversionRate": 0.68,
    "stages": [
      {
        "stage": "LEAD",
        "count": 5,
        "value": 875000,
        "averageProbability": 25
      },
      {
        "stage": "QUALIFIED",
        "count": 8,
        "value": 1400000,
        "averageProbability": 45
      },
      {
        "stage": "NEGOTIATION",
        "count": 6,
        "value": 1200000,
        "averageProbability": 70
      },
      {
        "stage": "CONTRACT",
        "count": 4,
        "value": 950000,
        "averageProbability": 90
      },
      {
        "stage": "CLOSING",
        "count": 3,
        "value": 600000,
        "averageProbability": 95
      }
    ]
  }
}

Move Deal to Stage

Move a deal to a different pipeline stage.

curl -X POST "https://api.winnerr.com/v1/deals/deal_123/move" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stage": "CONTRACT",
    "reason": "Offer accepted by seller",
    "probability": 90
  }'

const response = await fetch('https://api.winnerr.com/v1/deals/deal_123/move', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    stage: 'CONTRACT',
    reason: 'Offer accepted by seller',
    probability: 90
  })
});

const result = await response.json();

Deal Analytics

Get Deal Metrics

Retrieve analytics and performance metrics for deals.

curl -X GET "https://api.winnerr.com/v1/deals/analytics" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

const response = await fetch('https://api.winnerr.com/v1/deals/analytics', {
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  }
});

const analytics = await response.json();

Query Parameters:

Parameter	Type	Description
`period`	string	Time period (7d, 30d, 90d, 1y)
`assignedTo`	string	Filter by assigned agent
`type`	string	Filter by deal type

Response:

{
  "success": true,
  "data": {
    "period": "30d",
    "totalDeals": 28,
    "closedDeals": 8,
    "totalValue": 5250000,
    "closedValue": 1800000,
    "averageTimeToClose": 45,
    "conversionRate": 0.68,
    "topPerformers": [
      {
        "agentId": "agent_123",
        "name": "Sarah Johnson",
        "deals": 12,
        "closedValue": 850000
      }
    ]
  }
}

Webhooks

Deal Events

Supported webhook events for deals:

deal.created
deal.updated
deal.stage_changed
deal.closed
deal.lost
deal.document_uploaded
deal.task_created
deal.task_completed

Webhook Payload Example

{
  "id": "evt_123456789",
  "event": "deal.stage_changed",
  "createdAt": "2024-01-15T14:30:00Z",
  "data": {
    "id": "deal_123",
    "title": "Miami Waterfront Condo Sale",
    "previousStage": "QUALIFIED",
    "newStage": "NEGOTIATION",
    "amount": 750000,
    "probability": 70
  },
  "organization": {
    "id": "org_123",
    "name": "Premier Realty Group"
  }
}

Best Practices

1. Pipeline Management

Regularly update deal stages and probabilities:

// Update deal stage with probability adjustment
await fetch('https://api.winnerr.com/v1/deals/deal_123', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    stage: 'NEGOTIATION',
    probability: 75, // Adjust based on stage
    notes: 'Buyer submitted counter-offer'
  })
});

2. Task Management

Create tasks automatically when deals progress:

// Create inspection task when deal reaches contract stage
if (deal.stage === 'CONTRACT') {
  await fetch(`https://api.winnerr.com/v1/deals/${deal.id}/tasks`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'Schedule inspection',
      dueDate: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // 7 days from now
      priority: 'HIGH'
    })
  });
}

3. Document Management

Organize documents by type and stage:

// Upload document with proper categorization
const formData = new FormData();
formData.append('file', contractFile);
formData.append('name', 'Signed Purchase Agreement');
formData.append('type', 'CONTRACT');
formData.append('stage', 'CONTRACT');

await fetch(`https://api.winnerr.com/v1/deals/${dealId}/documents`, {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_JWT_TOKEN' },
  body: formData
});

4. Performance Tracking

Monitor deal performance regularly:

// Get pipeline metrics for performance analysis
const metrics = await fetch('https://api.winnerr.com/v1/deals/pipeline', {
  headers: { 'Authorization': 'Bearer YOUR_JWT_TOKEN' }
});

// Identify bottlenecks and optimization opportunities
const bottlenecks = metrics.data.stages.filter(stage => 
  stage.averageProbability < 0.5 && stage.count > 5
);

Deal data is automatically synchronized with your CRM dashboard, analytics, and commission tracking. All deal activities are logged for audit and compliance purposes.

​Deal Object

​Deal Properties

​Deal Types

​Deal Stages

​Deal Status

​Endpoints

​List Deals

​Get Deal

​Create Deal

​Update Deal

​Delete Deal

​Deal Tasks

​List Deal Tasks

​Create Deal Task

​Deal Documents

​List Deal Documents

​Upload Deal Document

​Deal Activities

​List Deal Activities

​Pipeline Management

​Get Pipeline Overview

​Move Deal to Stage

​Deal Analytics

​Get Deal Metrics

​Webhooks

​Deal Events

​Webhook Payload Example

​Best Practices

​1. Pipeline Management

​2. Task Management

​3. Document Management

​4. Performance Tracking

Deal Object

Deal Properties

Deal Types

Deal Stages

Deal Status

Endpoints

List Deals

Get Deal

Create Deal

Update Deal

Delete Deal

Deal Tasks

List Deal Tasks

Create Deal Task

Deal Documents

List Deal Documents

Upload Deal Document

Deal Activities

List Deal Activities

Pipeline Management

Get Pipeline Overview

Move Deal to Stage

Deal Analytics

Get Deal Metrics

Webhooks

Deal Events

Webhook Payload Example

Best Practices

1. Pipeline Management

2. Task Management

3. Document Management

4. Performance Tracking