SAAS saas_plat openapi batch_create - nxtele/nxcloud-doc-en GitHub Wiki

Batch Create Customer

  • URL: https://api-hk.nxlink.ai/saas/cdp/openapi/customers/batch_create
  • Method: POST
  • Content-Type: application/json
  • Authentication: Required

Request Parameters

Header Parameters:

Parameter Type Required Example Description
accessKey String Yes fme2na3kdi3ki User identity identifier
ts String Yes 1655710885431 Current request timestamp (in milliseconds), NXCloud server allows maximum time difference of 60 seconds
bizType String Yes 2 WhatsApp business type, fixed value "2"
action String Yes mt WhatsApp business operation, fixed value "mt"
sign String Yes 6e9506557d1f289501d333ee2c365826 API parameter signature, see common conventions

Body Parameters:

Parameter Type Required Example Description
type integer Yes 1 0: Discard old data, use new data 1: Update/add data items based on old data 2: Keep old data, discard new data
tenant_id integer Yes 123 Tenant ID
app_key string Yes 46oKF=os App key
strict_binding boolean No false Whether to enable strict binding mode for one-to-one customer-seat relationship, default false
customers array Yes customers info Batch create, maximum 100 per request

Customer Parameters:

Parameter Type Required Example Description
full_name String Yes - Customer name, maximum length 255 characters
first_name String No - First name, maximum length 128 characters
last_name String No - Last name, maximum length 128 characters
sms_phone String No - Mobile phone number, maximum length 30 characters, digits only
whats_app_phone String No - WhatsApp number, maximum length 30 characters, digits only
viber_phone String No - Viber phone, maximum length 30 characters, digits only
messenger String No - Messenger, maximum length 32 characters, digits only
instagram String No - Instagram, maximum length 32 characters, digits only
zalo String No - Zalo, maximum length 32 characters, digits only
line String No - Line, maximum length 50 characters
country String No - Country, maximum length 50 characters
email String No - Email, maximum length 50 characters
address String No - Street address, maximum length 100 characters
birthday String No - Birthday, format: yyyy-MM-dd
tagStr String No - Tag names, comma-separated
remark String No - Remarks, maximum length 2000 characters
time_zone String No - Time zone
gender integer No - Gender, 1 for male, 0 for female
customize_field String No - Custom field data, JSON format string
belong_seat_user String No - Belonging seat user, maximum length 128 characters. Optional field, if not provided, customer will be created successfully without validation
weight integer No - Customer level, value range 1-5

Notes:

  • sms_phone, whats_app_phone, email, viber_phone, messenger, instagram, line, zalo cannot all be empty
  • Phone number fields (sms_phone, whats_app_phone, viber_phone, messenger, instagram, zalo) must be digits only
  • belong_seat_user is optional, if not provided, customer will be created successfully without validation
  • When strict_binding=true, if belong_seat_user does not exist, the record will be added to failItems and other records will continue to be processed

Request Example

Batch Create Request Example

body (application/json) parameters:

{
    "type": 0,
    "tenant_id": 123,
    "strict_binding": true,
    "customers": [
        {
            "full_name": "zhang san",
            "first_name": "san",
            "last_name": "zhang",
            "sms_phone": "18163725558",
            "whats_app_phone": "8618163725558",
            "viber_phone": "8618163725558",
            "country": "China",
            "email": "[email protected]",
            "address": "Wujin District, Tai'an City, Fujian Province",
            "birthday": "1976-04-12",
            "remark": "Important customer",
            "tagStr": "test,99",
            "time_zone": "GMT+8",
            "gender": 1,
            "belong_seat_user": "[email protected]",
            "weight": 5,
            "line": "line123456",
            "zalo": "1234567890",
            "messenger": "9876543210",
            "instagram": "1122334455",
            "customize_field": "{\"customize_1_14\": \"aa\"}"
        },
        {
            "full_name": "li si",
            "first_name": "si",
            "last_name": "li",
            "sms_phone": "18135539411",
            "whats_app_phone": "8618135539411",
            "country": "China",
            "email": "[email protected]",
            "address": "Wujin District, Tai'an City, Fujian Province",
            "birthday": "2015-08-19",
            "remark": "Regular customer",
            "time_zone": "GMT+8",
            "tagStr": "88,99",
            "gender": 1,
            "belong_seat_user": "[email protected]"
        }
    ]
}

Response Parameters

Response Structure

Parameter Type Description
code Integer Result code
data JsonObject Request result
message String Result message
traceId String Trace ID

Data Field Structure (BatchCreateResultVO)

Parameter Type Description
totalCount Integer Total count
successCount Integer Success count
failCount Integer Failure count
failItems Array Failure details list
successItems Array Success details list

FailItem Structure

Parameter Type Description
index Integer Position in request
errorCode Integer Error code
errorMessage String Error message

SuccessItem Structure

Parameter Type Description
index Integer Position in request
customerId Long Customer ID
whatsAppPhone String WhatsApp phone number

Response Examples

Success Example (All Successful)

{
    "code": 0,
    "message": null,
    "traceId": "56bf81643292cd6a89ecde64ae00db13",
    "data": {
        "totalCount": 2,
        "successCount": 2,
        "failCount": 0,
        "failItems": [],
        "successItems": [
            {
                "index": 0,
                "customerId": 1214631327620775936,
                "whatsAppPhone": "8618163725558"
            },
            {
                "index": 1,
                "customerId": 1214631327620775937,
                "whatsAppPhone": "8618135539411"
            }
        ]
    }
}

Partial Success Example (when strict_binding=true)

{
    "code": 0,
    "message": null,
    "traceId": "de31e85fdcc9489f9a7b8c99193b9a93",
    "data": {
        "totalCount": 2,
        "successCount": 1,
        "failCount": 1,
        "failItems": [
            {
                "index": 1,
                "errorCode": 12148,
                "errorMessage": "The belonging seat agent1 does not exist. Please go to Management->Members to confirm"
            }
        ],
        "successItems": [
            {
                "index": 0,
                "customerId": 1214631327620775936,
                "whatsAppPhone": "8618163725558"
            }
        ]
    }
}

Failure Example (when strict_binding=false, entire request fails)

{
    "code": 12148,
    "message": "The belonging seat agent1 does not exist. Please go to Management->Members to confirm",
    "traceId": "4516857e03a84c4cbe1339a93f24a1b6",
    "data": null
}
⚠️ **GitHub.com Fallback** ⚠️