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
  • address
    Type: string
    max length:  
    256    nullable

    Address - Physical address or location

  • companyId
    Type: string
    min length:  
    2
    max length:  
    50    nullable

    Company ID - ID of the company this person is associated with. Must be a valid company ID starting with 'c-'

  • deskPhone
    Type: string
    max length:  
    100    nullable

    Desk Phone - Direct office phone number

  • email
    Type: string
    max length:  
    256    nullable

    Email Address - Primary email address. Can contain multiple emails separated by semicolons

  • firstName
    Type: string
    max length:  
    256    nullable

    First Name - Contact's first name

  • jobFunction
    Type: integernullable

    Job Function ID - Standardized job function category (e.g., Engineering, Sales, Marketing)

  • jobTitle
    Type: string
    max length:  
    256    nullable

    Job Title - Person's current job title or position

  • lastName
    Type: string
    max length:  
    256    nullable

    Last Name - Contact's last name

  • notes
    Type: string
    max length:  
    8192    nullable

    Notes - Free-form notes about the person, their preferences, or important context

  • phone
    Type: string
    max length:  
    256    nullable

    Phone Number - Primary phone number for the contact

  • referenceability
    Type: enumnullable

    Referenceability - Willingness and ability to serve as a customer reference

    values
    1234
  • reportsTo
    Type: string
    min length:  
    2
    max length:  
    50    nullable

    Reports To - ID of the person this contact reports to in their organization. Must be a valid person ID starting with 'p-'

  • propertyName
    additionalPropertyType: anything

Responses

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/
curl 'https://crm.dreamhub.ai/api/v1/people/?match_existing=true' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "firstName": "John",
  "lastName": "Smith",
  "companyId": "c-acme123",
  "jobTitle": "VP of Engineering",
  "phone": "+1-555-123-4567",
  "email": "john.smith@acme.com",
  "jobFunction": 1,
  "deskPhone": "+1-555-123-4567 ext. 123",
  "reportsTo": "p-manager123",
  "notes": "Prefers email communication",
  "address": "123 Main St, San Francisco, CA 94105",
  "referenceability": 1,
  "status": 1,
  "statusReasonText": "Left company",
  "statusChangedBy": "u-user123",
  "statusChangedAt": "2024-01-15T10:30:00Z",
  "additionalProperty": "anything"
}'

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

The payload matched an existing person and updated it.