AgencyHandy API：新しいクライアントをプログラムで作成する

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

Prerequisites

✅ API key generated from Workspace Config → API Key

Endpoint

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

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 clients in a single request.

string

必須

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

firstName

string

必須

The client’s first name.

lastName

string

必須

The client’s last name.

status

string

必須

The client’s status. The only accepted value for this endpoint is Client.

password

string

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

contactNo

string

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

country

string

The client’s country. Optional.

city

string

The client’s city. Optional.

state

string

The client’s state or region. Optional.

zipCode

string

The client’s ZIP or postal code. Optional.

address

string

The client’s address. Optional.

Full payload example

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

[
  {
    "email": "john.doe@example.com",
    "status": "Client",
    "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
          }
        ]
      }
    ]
  }
]

customFields[]._id

string

必須

The custom field ID when sending a custom field response.

customFields[].stringValue

string

Optional string response value.

customFields[].numberValue

number

Optional number response value.

customFields[].dateValue

string

Optional date response value.

customFields[].booleanValue

boolean

Optional boolean response value.

customFields[].arrayValue

array

Optional array response value. Each item can include value and label.

customFields[].fileValue

array

Optional file response value. Each file item must include _id, link, sizeInBytes, s3Key, type, company, and isVersion.

Example request

cURL

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

Success response

{
  "success": true,
  "data": {
    "addedClients": [
      {
        "_id": "NEW_MEMBER_ID",
        "email": "john.doe@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "name": "John Doe",
        "status": "Client",
        "source": "website",
        "isConvertedClient": true,
        "isAccountVerified": true,
        "isApproved": true
      }
    ],
    "notAddedClients": []
  }
}

success

boolean

Indicates whether at least one client was added.

data.addedClients

array

Clients that were created, restored, or converted from existing leads.

data.addedClients[].\_id

string

Unique ID of the newly created client. Use this ID when assigning the client to orders or invoices via the API.

data.addedClients[].name

string

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

data.addedClients[].status

string

The status of the client as stored.

data.notAddedClients

array

Clients that were not created. Each item includes the submitted email and a reason, such as Client already exists or One or more category not found.

You can pass up to 200 client objects in the array. If a submitted email belongs to an existing lead, AgencyHandy converts that lead into a client.

はじめに

エンドポイント

AgencyHandy API：新しいクライアントをプログラムで作成する

Prerequisites

Endpoint

Headers

Request body

Full payload example

Example request

Success response

​Prerequisites

​Endpoint

​Headers

​Request body

​Full payload example

​Example request

​Success response

Prerequisites

Endpoint

Headers

Request body

Full payload example

Example request

Success response