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
    max length:  
    256
    required

    Lead name - A descriptive name for the lead, typically including company and opportunity details

  • aeOwner
    Type: string
    max length:  
    50    nullable

    AE Owner - Account Executive who will handle the lead if qualified. Must be a valid user ID starting with 'u-'

  • closedAsQualifiedReason
    Type: integernullable

    Qualification Reason - Why the lead was marked as qualified (required when status is CLOSED_QUALIFIED)

  • companyId
    Type: string
    max length:  
    50    nullable

    Company ID - Associated company for this lead. Must be a valid company ID starting with 'c-'

  • contactId
    Type: string
    max length:  
    50    nullable

    Contact ID - Primary contact person for this lead. Must be a valid person ID starting with 'p-'

  • conversionProbability
    Type: numbernullable

    Conversion Probability - Estimated likelihood of converting to a qualified opportunity (0.0 to 1.0)

  • createdAt
    Type: stringFormat: date-timenullable

    Creation Date - When the lead was first created in the system

  • disqualifiedCompanyReason
    Type: integernullable

    Company Disqualification Reason - Reason for disqualifying the entire company

  • disqualifiedReason
    Type: integernullable

    Disqualification Reason - Why the lead was disqualified (required when status is DISQUALIFIED)

  • engagementScore
    Type: enumnullable

    Engagement Score - Measures the lead's level of interest and interaction (COLD, LUKEWARM, ON_FIRE)

    values
    123
  • inboundCampaignType
    Type: integernullable

    Inbound Campaign Type - Specific inbound marketing campaign that generated this lead

  • licenseId
    Type: stringnullable

    License ID - Specific product license being evaluated or discussed

  • propertyName
    additionalPropertyType: anything

Responses

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/
curl 'https://crm.dreamhub.ai/api/v1/leads/?match_existing=true' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "name": "Acme Corp - Enterprise Platform Evaluation",
  "sdrOwner": "u-abc123",
  "aeOwner": "u-xyz789",
  "companyId": "c-company123",
  "contactId": "p-contact789",
  "status": 1,
  "createdAt": "2024-01-15T10:30:00Z",
  "engagementScore": 1,
  "conversionProbability": 0.75,
  "source": 1,
  "disqualifiedReason": 1,
  "disqualifiedCompanyReason": 2,
  "closedAsQualifiedReason": 1,
  "statusNotes": "Waiting for budget approval from CFO",
  "statusChangedBy": "u-user123",
  "statusChangedAt": "2024-01-20T14:45:00Z",
  "licenseId": "l-license123",
  "productId": "prod-platform",
  "numberOfLicenses": 10,
  "salesExplorationMeetingDate": "2024-02-01T15:00:00Z",
  "inboundCampaignType": 1,
  "outboundCampaignType": 2,
  "referringCompany": "c-referrer123",
  "referringPerson": "p-referrer456",
  "otherCompanyName": "Subsidiary Corp",
  "otherPersonName": "John Smith (Decision Maker)",
  "partnerId": "ptn-partner123",
  "partnerContactId": "ptc-contact789",
  "additionalProperty": "anything"
}'

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

The payload matched an existing lead and updated it.