Skip to main content
The Create Client endpoint lets you add clients directly to your AgencyHandy workspace from an external system. Unlike leads, clients are fully onboarded contacts who can be assigned to orders, invoices, and projects. Use this endpoint to sync new clients from a CRM, onboarding form, or any other data source.
Before using this endpoint, complete the Getting Started guide to obtain your API key and Company ID. Unlike the Create Lead endpoint, creating a client does not require a separate Role ID lookup step.

​
Prerequisites

  • ✅ API key generated from Workspace Config → API Key
  • ✅ Company ID retrieved from GET {{URL}}/accounts/companies

​
Endpoint

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

​
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 clients in a single request.
​
firstName
string
required
The client’s first name.
​
lastName
string
required
The client’s last name.
​
email
string
required
The client’s email address. Must be unique within your workspace.
​
isConvertedClient
boolean
required
Set to false for a brand-new client. Set to true when converting an existing lead into a client.
​
status
string
The client’s status. Common values: New, Active. Defaults to New if omitted.
​
contactNo
string
The client’s phone number.
​
source
string
How you acquired this client. Example values: website, referral, social.
​
positionInBoard
number
The client’s position within the board column. Defaults to 1.

​
Example request

cURL
curl --request POST "https://api.agencyhandy.com/members/bulk-client" \
  --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",
      "isConvertedClient": false,
      "status": "New",
      "contactNo": "1234567890",
      "source": "website",
      "positionInBoard": 1
    }
  ]'

​
Success response

{
  "message": "Client created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}
​
message
string
Confirmation string on success.
​
createdMembers
array
Array of created client objects.
​
createdMembers[].\_id
string
Unique ID of the newly created client. Use this ID when assigning the client to orders or invoices via the API.
​
createdMembers[].name
string
The full name of the client (firstName + lastName).
​
createdMembers[].status
string
The status of the client as stored.
​
createdMembers[].role
string
The role assigned to the member — will be "client".
The companyId header for this endpoint uses a capital I in Id — companyId — unlike some other endpoints that use companyid (all lowercase). Use the exact casing shown above to avoid authentication errors.
Pass multiple client objects in the array to bulk-create clients in a single API call. Each object must have a unique email address. Duplicate emails will cause a validation error for that entry.