AgencyHandy API: Programatik Olarak Yeni Lead Oluşturun

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.

type

string

gerekli

The lead type. Allowed values: individual, leadCompanyMember.

string

gerekli

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

status

string

gerekli

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

password

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.

firstName

string

The lead’s first name. Optional.

lastName

string

The lead’s last name. Optional.

contactNo

string

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

country

string

The lead’s country. Optional.

city

string

The lead’s city. Optional.

state

string

The lead’s state or region. Optional.

zipCode

string

The lead’s ZIP or postal code. Optional.

address

string

The lead’s address. Optional.

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": []
  }
}

success

boolean

Indicates whether the request was processed successfully.

data.addedLeads

array

Leads that were created successfully.

data.addedLeads[].\_id

string

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

data.addedLeads[].name

string

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

data.addedLeads[].status

string

The pipeline status of the lead as stored.

data.notAddedLeads

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.

Giriş

Uç Noktalar

AgencyHandy API: Programatik Olarak Yeni Lead Oluşturun

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