AgencyHandy API: Create a New Lead Programmatically

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. You do not need to send a company ID or role ID. AgencyHandy assigns the lead to the workspace client role automatically.

Prerequisites

✅ API key generated from Workspace Config → API Key

Create new leads

Endpoint

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

Headers

Header	Value
`x-api-key`	Your API key
`Content-Type`	`application/json`

Request body

The request body is a JSON array — you can create one or more leads in a single call.

string

required

The lead type. Allowed values: individual, leadCompanyMember.

string

required

The lead’s email address. It must be valid and should be unique within your workspace.

string

required

The lead’s pipeline status. Allowed values: New, Contacted, Qualified, Working, Proposal Sent, Negotiation.

string

Optional password for the lead. If provided, it must contain at least 8 characters, one uppercase letter, one lowercase letter, one number, and one special character.

string

The lead’s first name. Optional.

string

The lead’s last name. Optional.

string

The lead’s phone number. Optional. Defaults to an empty string if omitted.

string

The lead’s country. Optional.

string

The lead’s city. Optional.

string

The lead’s state or region. Optional.

string

The lead’s ZIP or postal code. Optional.

string

The lead’s address. Optional.

string[]

Optional array of category or label IDs. Each ID must exist in the workspace.

string

The lead’s company name. Optional.

boolean

Whether to send an invitation email. Optional. Defaults to true.

string

How you acquired this lead. Optional. Example values: website, referral, social.

string

The estimated value of the lead. Optional.

string

The lead’s website. Optional.

string

Optional assigned agent ID.

string

Optional date for when the lead was last contacted.

string[]

Optional array of file IDs attached to the lead.

string

Optional profile image URL or file reference.

array

Optional custom field responses for lead custom fields.

string

Optional currency code for a closed-won deal amount.

number

Optional closed-won deal amount. Can be null or an empty string.

string

Optional date of the lead’s last engagement.

string

Optional last engagement type. Allowed values: Email, Phone, One-to-One, Online Meeting.

string

Optional date of the first outreach.

string

Optional disqualification reason. Can be null or an empty string.

number

Optional email activity count. Can be null or an empty string.

string

Optional date of the last activity.

number

Optional meeting count. Can be null or an empty string.

number

Optional message thread count. Can be null or an empty string.

number

Optional outreach activity count. Can be null or an empty string.

Do not send role, isConvertedClient, or positionInBoard. The endpoint does not use those fields. Unknown fields are removed during validation.

Full payload example

Only type, email, and status are required. Every other field shown here is optional.

[
  {
    "type": "individual",
    "email": "john.doe@example.com",
    "status": "New",
    "password": "StrongPass1!",
    "firstName": "John",
    "lastName": "Doe",
    "contactNo": "1234567890",
    "country": "United States",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "address": "123 Main Street",
    "category": ["6525994184e9ddd798534535"],
    "companyName": "Example Inc.",
    "sendInvitationEmail": true,
    "source": "website",
    "leadValue": "2500",
    "website": "https://example.com",
    "agent": "6525994184e9ddd798534536",
    "lastContactedAt": "2026-07-19T10:00:00.000Z",
    "files": ["6525994184e9ddd798534537"],
    "profileImage": "https://example.com/avatar.png",
    "customFields": [
      {
        "_id": "6525994184e9ddd798534538",
        "stringValue": "Interested in monthly services",
        "numberValue": 2500,
        "dateValue": "2026-07-19T00:00:00.000Z",
        "booleanValue": true,
        "arrayValue": [
          {
            "value": "paid-search",
            "label": "Paid Search"
          }
        ],
        "fileValue": [
          {
            "_id": "6525994184e9ddd798534539",
            "link": "https://example.com/file.pdf",
            "sizeInBytes": "102400",
            "s3Key": "uploads/file.pdf",
            "type": "application/pdf",
            "company": "6525994184e9ddd798534540",
            "isVersion": false
          }
        ]
      }
    ],
    "closedWonDealCurrency": "USD",
    "closedWonDealAmount": 2500,
    "contactLastEngagementDate": "2026-07-19T10:00:00.000Z",
    "contactLastEngagementType": "Email",
    "firstOutreachDate": "2026-07-18T10:00:00.000Z",
    "disqualificationReason": "",
    "emailCount": 1,
    "lastActivityDate": "2026-07-19T10:00:00.000Z",
    "meetingCount": 0,
    "messageThreadCount": 1,
    "outreachActivityCount": 2
  }
]

Example request

cURL

curl --request POST "https://api.agencyhandy.com/members/bulk-lead" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '[
    {
      "type": "individual",
      "email": "john.doe@example.com",
      "status": "New",
      "firstName": "John",
      "lastName": "Doe",
      "contactNo": "1234567890",
      "source": "website",
      "leadValue": "2500",
      "website": "https://example.com",
      "sendInvitationEmail": true
    }
  ]'

Success response

{
  "success": true,
  "data": {
    "addedLeads": [
      {
        "_id": "NEW_MEMBER_ID",
        "type": "individual",
        "email": "john.doe@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "name": "John Doe",
        "status": "New",
        "positionInBoard": 1,
        "source": "website",
        "leadValue": "2500",
        "website": "https://example.com",
        "isConvertedClient": false,
        "isAccountVerified": true
      }
    ],
    "notAddedLeads": []
  }
}

boolean

Indicates whether the request was processed successfully.

array

Leads that were created successfully.

string

The unique ID of the newly created lead. Store this if you need to reference the lead in subsequent API calls.

string

The full name of the lead (firstName + lastName).

string

The pipeline status of the lead as stored.

array

Leads that were not created. Each item includes the submitted email, a reason, and sometimes the existing lead object.

You can pass up to 200 lead objects in the array. A valid request returns 201 when at least one lead is added, or 200 when all submitted leads are skipped, such as duplicates.

Introduction

Endpoints

AgencyHandy API: Create a New Lead Programmatically

Prerequisites

Create new leads

Endpoint

Headers

Request body

Full payload example

Example request

Success response

​Prerequisites

​Create new leads

​Endpoint

​Headers

​Request body

​Full payload example

​Example request

​Success response

Prerequisites

Create new leads

Endpoint

Headers

Request body

Full payload example

Example request

Success response