Create Entity

​

Create a new entity with the provided data.

This endpoint creates a new entity using the data provided in the request body. The entity will be validated according to the defined schema and business rules.

Args: entity_info: Complete entity data for creation including: - All required fields as defined in the entity schema - Optional fields with default values - Custom field values if applicable match_existing: Whether to match the payload against an existing entity on its natural key before creating (see the query parameter description). Entity types with no natural key ignore this and always create. user: Authenticated user information (used for audit trails) response: HTTP response object for status code modification

Returns: EntityResponseModel containing: - id: Unique identifier of the newly created entity, or of the existing entity the payload matched - matched: True when the payload matched an existing entity and updated it rather than creating a new one

Note: - Returns HTTP 201 (Created) on successful creation - Returns HTTP 200 (OK) when the payload matched an existing entity - Returns HTTP 206 (Partial Content) if entity is created but some custom fields failed to save - Automatically sets creation timestamp and user information

Raises: HTTPException: - 400: Invalid input data or validation errors - 401: Authentication required - 403: Insufficient permissions to create entities - 409: Entity already exists (if applicable) - 422: Validation error in request data - 500: Internal server error during creation

Query Parameters

  • match_existing
    Type: boolean

    Match the record against an existing one on its natural key (contacts on email, companies on website domain and name) when the payload carries no id, and update that record instead of creating a duplicate. Set false to always create.

Body·

required
application/json
  • name
    Type: string
    required

    Deal name - A descriptive name for the deal (e.g., 'Acme Corp - Enterprise License')

  • aeConfidenceLevel
    Type: enumnullable

    AE Confidence - Account Executive's confidence level in closing this deal

    values
    1234
  • aiAssignedProbability
    Type: number
    min:  
    0
    max:  
    100    nullable

    AI Probability - Machine learning calculated probability of deal success (0-100%)

  • amountBreakdownByPeriod
    nullable

    Payment Schedule - Breakdown of payments by time period (monthly, quarterly, annually)

    Payment Schedule - Breakdown of payments by time period (monthly, quarterly, annually)

    • propertyName
      additionalPropertyType: anything
  • annualContractValue
    Type: numbernullable

    Annual Contract Value (ACV) - Normalized annual value of the contract

  • arr
    Type: numbernullable

    Annual Recurring Revenue - Expected annual recurring revenue from this deal

  • arrLocal
    Type: numbernullable

    Annual Recurring Revenue (Local) - ARR in account's system currency

  • autoRenewal
    Type: booleannullable

    Auto-renewal - Whether the contract automatically renews

  • closedAt
    Type: stringFormat: date-timenullable

    Actual Close Date - Date when the deal was actually closed (for closed deals only)

  • closedLostReason
    Type: integernullable

    Loss Reason ID - Identifier for the reason why the deal was lost (required if status is closed_lost)

  • closedLostReasonText
    Type: stringnullable

    Loss Reason Details - Additional details about why the deal was lost

  • companyId
    Type: stringnullable

    Company - Unique identifier of the company this deal is associated with

  • propertyName
    additionalPropertyType: anything

Responses

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/
curl 'https://crm.dreamhub.ai/api/v1/deals/?match_existing=true' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "name": "Acme Corp - Enterprise License Q1 2024",
  "managedBy": "550e8400-e29b-41d4-a716-446655440000",
  "companyId": "550e8400-e29b-41d4-a716-446655440001",
  "contactId": "550e8400-e29b-41d4-a716-446655440002",
  "leadId": "550e8400-e29b-41d4-a716-446655440003",
  "status": "active",
  "stage": 3,
  "movedToStageAt": "2024-01-15T10:30:00Z",
  "expectedCloseAt": "2024-03-31T23:59:59Z",
  "closedAt": "2024-03-28T14:30:00Z",
  "dealValueAmount": 125000,
  "arr": 50000,
  "mrr": 4166.67,
  "arrLocal": 50000,
  "mrrLocal": 4166.67,
  "probability": 75,
  "techEvaluationStatus": 1,
  "qualificationScore": 85.5,
  "aeConfidenceLevel": 1,
  "aiAssignedProbability": 78.3,
  "closedLostReason": 3,
  "closedLostReasonText": "Customer chose competitor due to lower pricing",
  "manuallyAddedPeople": [
    "550e8400-e29b-41d4-a716-446655440004",
    "550e8400-e29b-41d4-a716-446655440005"
  ],
  "manuallyAddedPartnerContacts": [
    "ptc-abc123",
    "ptc-def456"
  ],
  "contractStartDate": "2024-04-01T00:00:00Z",
  "contractEndDate": "2025-03-31T23:59:59Z",
  "optOutDate": "2024-06-30T23:59:59Z",
  "contractTotalAmount": 150000,
  "amountBreakdownByPeriod": [
    {
      "amount": 37500,
      "period": "2024-Q1"
    },
    {
      "amount": 37500,
      "period": "2024-Q2"
    }
  ],
  "autoRenewal": true,
  "licenseId": "ENT-2024-001",
  "productId": "PROD-ENTERPRISE",
  "licensesInDeal": 50,
  "potentialLicensesInCompany": 200,
  "implementationCost": 15000,
  "trainingCost": 5000,
  "uploadContracts": {
    "contract_v1.pdf": {
      "size": 1024000,
      "uploaded_at": "2024-01-15T10:00:00Z"
    }
  },
  "annualContractValue": 125000,
  "totalContractValue": 375000,
  "currency": "USD",
  "contractId": "CONTRACT-2024-001",
  "partnerId": "ptn-acme-550e8400",
  "partnerContactId": "ptc-jane-550e8400",
  "additionalProperty": "anything"
}'

{
  "id": "string",
  "matched": false
}

The payload matched an existing deal and updated it.