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

Batch Create Customers

Batch create customers.

  • URL: https://api-idn.nxlink.ai/saas/cdp/openapi/customers/batch_create
  • Method: POST
  • Content-Type: application/json
  • Requires authentication: Yes

Request Parameters

Header Parameters

Parameter Type Required Example Description
accessKey String Yes fme2na3kdi3ki User identity key
ts String Yes 1655710885431 Timestamp in milliseconds. Max allowed time drift is 60 seconds.
bizType String Yes 2 WhatsApp business type, fixed value "2"
action String Yes mt WhatsApp action, fixed value "mt"
sign String Yes 6e9506557d1f289501d333ee2c365826 Signature, see common auth rules

Body Parameters

Parameter Type Required Example Description
type integer Yes 1 0: drop old data, use new; 1: update/add based on old; 2: keep old, drop new
tenant_id integer Yes 123 Tenant ID
app_key string Yes 46oKF=os App key
strict_binding boolean No false Enable strict customer-seat binding. Default false
customers array Yes customers Batch customers, max 100 per request

Message Types

  • customers parameters:
Parameter Type Required Example Description
full_name String Yes - Customer name, max 255 chars
first_name String No - First name, max 128 chars
last_name String No - Last name, max 128 chars
sms_phone String No - SMS phone, numeric, max 30 chars
whats_app_phone String No - WhatsApp phone, numeric, max 30 chars
viber_phone String No - Viber phone, numeric, max 30 chars
messenger String No - Messenger ID, numeric, max 32 chars
instagram String No - Instagram ID, numeric, max 32 chars
zalo String No - Zalo ID, numeric, max 32 chars
line String No - Line ID, max 50 chars
country String No - Country, max 50 chars
email String No - Email, max 50 chars
address String No - Address, max 100 chars
birthday String No - Birthday, format yyyy-MM-dd
tagStr String No - Tag names, comma separated
remark String No - Remark, max 2000 chars
time_zone String No - Time zone
gender integer No - Gender, 1 male, 0 female
customize_field String No - Custom fields as JSON string
belong_seat_user String No - Assigned seat, max 128 chars. If empty, create directly
weight integer No - Customer level, 1-5

Notes

  • sms_phone, whats_app_phone, email, viber_phone, messenger, instagram, line, zalo cannot all be empty
  • Phone fields must be numeric
  • belong_seat_user is optional; if empty, created without validation
  • When strict_binding=true and belong_seat_user does not exist, that record goes to failItems; others continue

Request Example

Batch 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": "Normal 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 Result data
message String Message
traceId String Trace ID

data (BatchCreateResultVO)

Parameter Type Description
totalCount Integer Total count
successCount Integer Success count
failCount Integer Fail count
failItems Array Failed item details
successItems Array Success item details

FailItem

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

SuccessItem

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

Response Example

Success Example (all success)

{
    "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 (strict_binding=true)

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

Failure Example (strict_binding=false, overall failure)

{
    "code": 12148,
    "message": "Assigned seat agent1 does not exist. Please check Admin -> Members.",
    "traceId": "4516857e03a84c4cbe1339a93f24a1b6",
    "data": null
}
⚠️ **GitHub.com Fallback** ⚠️