Create Leads

Overview

The Create Leads endpoint allows you to programmatically insert leads into a specific ClosingDealz workspace.

This endpoint is designed for custom integrations, internal systems, backend services, and external lead sources that need to push structured lead data directly into ClosingDealz without using the UI.

You can create:

• Company leads
• Contact leads
• Leads with multiple associated contacts
• Leads with rich contact data (emails, phone numbers, socials, addresses)

Endpoint

POST /api/v1/leads

Headers

All requests must be authenticated using an API key.

Include your API key in the request headers:

X-API-Key: YOUR_API_KEY

Content-Type: application/json

Workspace Scope

Each API key is scoped to one workspace.

• All leads created via this endpoint will be inserted into the workspace that owns the API key
• You cannot create leads across multiple workspaces with a single API key

Request Body

The request body accepts an array of leads, allowing you to create multiple leads in a single request.

Example Body Request:

[
    {
        "isContact": false,
        "name": "Company Name",
        "industry": "Industry",
        "email": [{ "Address": "email@example.com" }],
        "phoneNumber": [{ "Number": "+1-555-204-7789" }]
    }
]

Visit Lead Request Objects to view all the available fields of the request. https://closingdealz.io/api/leads-api/create-leads

Example Curl Request:

Here’s an example of how to create a lead using curl:

curl -X POST https://app.closingdealz.io/api/v1/leads \
  -H 'X-API-Key: your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '[{ "isContact": false, "Name": "ClosingDealz" }]'

Replace your_api_key_here with your actual API key.

Rate Limiting

Requests are rate-limited per API key.

• 100 requests per minute
• Sliding window strategy
• Exceeding the limit returns 429 Too Many Requests

Success Responses

200 OK

Description: Successfully created leads.

{
  "succeeded": true,
  "statusCode": 200,
  "statusCodeDescription": "NONE",
  "message": null
}

Error Responses

401 Unauthorized

Description: The submitted API key was not valid.

{
  "succeeded": false,
  "statusCode": 401,
  "statusCodeDescription": "NONE",
  "message": "Invalid API key."
}

400 Bad Request

Description: Only 100 leads are allowed to be created at once.

{
  "succeeded": false,
  "statusCode": 400,
  "statusCodeDescription": "NONE",
  "message": "The maximum amount of leads to create at once is 100, but was {lead_count}."
}

400 Bad Request

Description: Workspace plan has been downgraded to Free Plan. Only workspaces with Basic Plan can use the API without limits.

{
  "succeeded": false,
  "statusCode": 400,
  "statusCodeDescription": "NONE",
  "message": "Reached the maximum limit of leads on the free plan."
}

400 Bad Request

Description: Cannot have more than 200 leads on the Free Plan. Only workspaces with Basic Plan can use the API without limits.

{
  "succeeded": false,
  "statusCode": 400,
  "statusCodeDescription": "NONE",
  "message": "Can not have more than 200 leads on the free plan."
}

429 Too Many Requests

Description: Too many requests. Please try again later.

{
  "succeeded": false,
  "statusCode": 429,
  "statusCodeDescription": "NONE",
  "message": "Too many requests. Please try again later."
}