Lead Request Object

Reference documentation for the Lead Request object, outlining all supported fields, data types, and constraints used when creating leads through the ClosingDealz API.

Lead Request Object

The Lead Request Object defines the structure used when creating leads through the ClosingDealz API.

A lead represents either:

A company lead, or
A contact lead

This object supports rich contact data, company grouping, labels, and multiple associated contacts.

Lead Record Fields

This section outlines the fields available for creating or updating a lead in the ClosingDealz CRM via the API. Each field includes its expected data type, whether it is required or optional, and any specific constraints.

Lead-Level Fields

Field Name	Data Type	Description	Constraints
`IsContact`	`boolean`	Determines the lead type. When `false`, the lead represents a company. When `true`, the lead represents a contact.	Required
`EmployeeCount`	`integer`	Number of employees associated with the company lead.	Optional. Range: `0`–`5,000,000`
`CompanyId`	`UUID`	Links the lead to an existing company record.	Optional
`Labels`	`string[]`	Labels applied to the lead for categorization and filtering.	Optional. Max length per label: 64 characters
`Contacts`	`CreateContactRequest[]`	Additional contacts associated with the lead.	Optional

Contact Fields (Inherited)

The Lead Request Object inherits all fields from the Contact Request Object. These fields can be used directly on the lead or inside the Contacts array.

Contact Record Fields

Field Name	Data Type	Description	Constraints
`ContactId`	`UUID`	References an existing contact record.	Optional
`Name`	`string`	First name of the contact.	Optional. Max length: 256
`LastName`	`string`	Last name of the contact.	Optional. Max length: 256
`Industry`	`string`	Industry associated with the contact or company.	Optional. Max length: 256
`Role`	`string`	Job title or role of the contact.	Optional. Max length: 256
`Socials`	`ContactSocial[]`	Social or web profiles linked to the contact.	Optional
`Emails`	`ContactEmailAddress[]`	Email addresses associated with the contact.	Optional
`PhoneNumbers`	`ContactPhoneNumber[]`	Phone numbers associated with the contact.	Optional
`Addresses`	`ContactAddress[]`	Physical or mailing addresses for the contact.	Optional
`Description`	`string`	Notes or additional context about the lead or contact.	Optional. Max length: 6942
`InterestLevel`	`enum (InterestLevel)`	Indicates the lead’s interest level.	Optional
`DateAcquired`	`datetime`	Date the contact or lead was acquired.	Optional

Contact Email Address Record Fields

Field Name	Data Type	Description	Constraints
`Address`	`string`	Email address value.	Max length: 124
`Type`	`enum (ContactPurposeType)`	Purpose of the email address (e.g. Home, Work).	Optional

Contact Phone Number Record Fields

Field Name	Data Type	Description	Constraints
`Number`	`string`	Phone number value.	Max length: 64
`Type`	`enum (ContactPhoneType)`	Type of phone number (e.g. Mobile, Work, Direct).	Optional

Field Name	Data Type	Description	Constraints
`Value`	`string`	Social profile URL or identifier.	Max length: 512
`Type`	`enum (ContactSocialType)`	Platform type (e.g. LinkedIn, Twitter, Website).	Optional
`PurposeType`	`enum (ContactPurposeType)`	Intended purpose of the social profile (e.g. Work, Home).	Optional

Contact Address Record Fields

Field Name	Data Type	Description	Constraints
`Address`	`string`	Street or address line.	Max length: 512
`City`	`string`	City name.	Max length: 256
`State`	`string`	State or region.	Max length: 256
`PostalCode`	`string`	Postal or ZIP code.	Max length: 256
`Country`	`string`	Country name.	Max length: 256
`Type`	`enum (ContactAddressType)`	Address type (e.g. Office, Billing, Shipping).	Optional

ContactPurposeType

Defines the purpose of a contact detail such as an email address or social profile.

Value	Description
`None`	No specific purpose defined.
`Home`	Personal or home-related contact detail.
`Work`	Work or business-related contact detail.

ContactPhoneType

Defines the type of a phone number.

Value	Description
`None`	No specific phone type defined.
`Home`	Home phone number.
`Work`	Work phone number.
`Mobile`	Mobile or cell phone number.
`Direct`	Direct line phone number.
`Fax`	Fax number.

ContactSocialType

Defines the platform or type of a social or web profile.

Value	Description
`Website`	Personal or company website.
`LinkedIn`	LinkedIn profile.
`Twitter`	Twitter (X) profile.
`Instagram`	Instagram profile.
`Facebook`	Facebook profile.
`Youtube`	YouTube channel or profile.
`Tiktok`	TikTok profile.
`Telegram`	Telegram account or channel.
`Discord`	Discord profile or server.
`Blog`	Blog or personal writing site.
`Github`	GitHub profile or repository.
`Pinterest`	Pinterest profile.

ContactAddressType

Defines the purpose of a physical or mailing address.

Value	Description
`None`	No specific address type defined.
`Home`	Residential or home address.
`Postal`	Postal or mailing address.
`Office`	Office or workplace address.
`Billing`	Billing address used for invoices.
`Shipping`	Shipping or delivery address.

InterestLevel

Represents the level of interest or qualification status of a lead or contact.

Value	Description
`Unknown`	Interest level has not been determined yet.
`Potential`	Shows early potential but not yet qualified.
`BadFit`	Not a good fit for the business or offering.
`Qualified`	Meets qualification criteria and is sales-ready.
`Interested`	Actively interested in the product or service.
`NotInterested`	Explicitly indicated no interest.
`Canceled`	Lead or opportunity was canceled or dropped.

Multiple Contacts & Company Grouping

A single lead can include multiple contacts
When multiple contacts share the same company, they are grouped under the same company lead
This allows one company record to contain several decision-makers or stakeholders

Example Json Payloads

Creating 1 company with 1 contact:

[
  {
    "IsContact": false,
    "Name": "BrightPeak Solutions",
    "Industry": "Marketing Services",
    "EmployeeCount": 42,
    "Labels": ["Inbound", "Qualified"],
    "Description": "Inbound lead from website chatbot",
    "Contacts": [
      {
        "Name": "Alex",
        "LastName": "Morgan",
        "Role": "Head of Growth",
        "InterestLevel": "Interested",
        "Emails": [
          {
            "Address": "alex.morgan@brightpeak.io",
            "Type": "Work"
          }
        ],
        "PhoneNumbers": [
          {
            "Number": "+1-555-204-7789",
            "Type": "Mobile"
          }
        ],
        "Socials": [
          {
            "Value": "https://www.linkedin.com/in/alex-morgan-brightpeak",
            "Type": "LinkedIn",
            "PurposeType": "Work"
          }
        ],
        "Addresses": [
          {
            "Address": "421 Market Street",
            "City": "San Francisco",
            "State": "CA",
            "PostalCode": "94105",
            "Country": "USA",
            "Type": "Office"
          }
        ],
        "Description": "Primary decision maker for marketing software"
      }
    ]
  }
]

Creating 1 company with 2 contacts

[
  {
    "IsContact": false,
    "Name": "Northline Systems",
    "Industry": "SaaS",
    "Labels": ["Inbound"],
    "Contacts": [
      {
        "Name": "Emma",
        "LastName": "Reed",
        "Role": "Founder",
        "Emails": [
          {
            "Address": "emma@northline.io",
            "Type": "Work"
          }
        ]
      },
      {
        "Name": "Daniel",
        "LastName": "Kerr",
        "Role": "Operations Manager",
        "Emails": [
          {
            "Address": "daniel@northline.io",
            "Type": "Work"
          }
        ]
      }
    ]
  }
]

Creating 2 companies (no contacts attached)

[
  {
    "IsContact": false,
    "Name": "Bluewave Consulting",
    "Industry": "Business Consulting",
    "Labels": ["Imported"]
  },
  {
    "IsContact": false,
    "Name": "Atlas Digital",
    "Industry": "Web Development",
    "Labels": ["Inbound"]
  }
]

Creating 2 standalone contacts (no company)

[
  {
    "IsContact": true,
    "Name": "Sofia",
    "LastName": "Nilsson",
    "Role": "Marketing Lead",
    "Emails": [
      {
        "Address": "sofia.nilsson@example.com",
        "Type": "Work"
      }
    ]
  },
  {
    "IsContact": true,
    "Name": "Liam",
    "LastName": "Berg",
    "Role": "Sales Manager",
    "Emails": [
      {
        "Address": "liam.berg@example.com",
        "Type": "Work"
      }
    ]
  }
]

Updated December 25, 2025

Introduction

Authentication

Leads API

Objects

Lead Request Object

Table of Contents