Skip to main content
The Create Lead endpoint lets you programmatically add new leads to your AgencyHandy workspace from any external system — a web form, a CRM, a marketing automation platform, or a custom script. Leads created via this endpoint appear in your lead pipeline immediately, just as if they were added manually.
Before using this endpoint, complete the Getting Started guide to obtain your API key and Company ID. You also need to fetch your Client Role ID, which is required when creating a lead.

​
Prerequisites

  • ✅ API key generated from Workspace Config → API Key
  • ✅ Company ID retrieved from GET {{URL}}/accounts/companies
  • ✅ Client Role ID retrieved (see Step 1 below)

​
Step 1: Get the Client Role ID

Before creating a lead, you need the Role ID for the client role in your company.

​
Endpoint

GET {{URL}}/roles?type=company

​
Headers

HeaderValue
x-api-keyYour API key
companyidYour Company ID

​
Example request

cURL
curl --request GET "https://api.agencyhandy.com/roles?type=company" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --header "companyid: <YOUR_COMPANY_ID>"

​
Example response

{
  "roles": [
    {
      "_id": "6525994184e9ddd798534535",
      "role": {
        "_id": "6525994184e9ddd79853451e",
        "responsibility": "",
        "name": "client"
      },
      "company": "6525994184e9ddd79853450e",
      "createdAt": "2023-10-10T18:34:41.567Z",
      "updatedAt": "2024-10-01T07:28:48.340Z",
      "__v": 0,
      "type": "company"
    }
  ]
}
Find the entry where roles[0].role.name === "client" and extract the outer _id — that is roles[0]._id, not roles[0].role._id. 
const clientRoleId = roles.find(r => r.role.name === "client")._id;
// e.g. "6525994184e9ddd798534535"
Use roles[0]._id (the company-role mapping ID), not roles[0].role._id (the role definition ID). Using the wrong ID causes the lead creation request to fail.

​
Step 2: Create a new lead

​
Endpoint

POST {{URL}}/members/bulk-lead

​
Headers

HeaderValue
x-api-keyYour API key
companyidYour Company ID
Content-Typeapplication/json

​
Request body

The request body is a JSON array — you can create one or more leads in a single call.
​
firstName
string
required
The lead’s first name.
​
lastName
string
required
The lead’s last name.
​
email
string
required
The lead’s email address. Must be unique within your workspace.
​
role
string
required
The Client Role ID retrieved in Step 1 (i.e., roles[0]._id).
​
isConvertedClient
boolean
required
Must be set to false when creating a lead. Set to true only when converting a lead into a full client.
​
status
string
The lead’s pipeline status. Common values: New, Contacted, Qualified. Defaults to New if omitted.
​
contactNo
string
The lead’s phone number.
​
source
string
How you acquired this lead. Example values: website, referral, social.
​
positionInBoard
number
The lead’s position (order) within the pipeline board column. Defaults to 1.

​
Example request

cURL
curl --request POST "https://api.agencyhandy.com/members/bulk-lead" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --header "companyid: <YOUR_COMPANY_ID>" \
  --header "Content-Type: application/json" \
  --data '[
    {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "role": "6525994184e9ddd798534535",
      "isConvertedClient": false,
      "status": "New",
      "contactNo": "1234567890",
      "source": "website",
      "positionInBoard": 1
    }
  ]'

​
Success response

{
  "message": "Lead created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}
​
message
string
Confirmation string: "Lead created successfully".
​
createdMembers
array
Array of created lead objects.
​
createdMembers[].\_id
string
The unique ID of the newly created lead. Store this if you need to reference the lead in subsequent API calls.
​
createdMembers[].name
string
The full name of the lead (firstName + lastName).
​
createdMembers[].status
string
The pipeline status of the lead as stored.
​
createdMembers[].role
string
The role name assigned to the member — will be "client".
You can pass multiple lead objects in the array to create several leads in a single API call. Each object must include all required fields with its own unique email address.