claudetools/.claude/skills/yealink-ymcs/docs/SIPSERVER_SCHEMA.md

YMCS SIP Account Schema - Critical Field Formats

Source: Open API for Yealink Management Cloud Service V4X, pages 59-60 (chunk-03)

Add SIP Account Endpoint

POST /v2/dm/sipAccounts

Complete Request Body Schema

Field	Type	Required	Description
registerName	String	Yes	Registered name, max 128 chars
username	String	Yes	Username, max 128 chars
password	String	Yes	Password, max 128 chars
displayName	String	No	Display name, max 128 chars
label	String	No	Label, max 128 chars
sipServer1	SipServer	Yes	SIP server 1 address (OBJECT, not string)
sipServer2	SipServer	No	SIP server 2 address (object)
remark	String	No	Note, max 512 chars
siteId	String	No	Site ID to assign

SipServer Object Definition

CRITICAL: sipServer1/sipServer2 are objects, not strings.

Field	Type	Description
host	String	Server address, max 256 chars
port	Integer	Server port, 0-65535

Working Example (from official docs)

POST /v2/dm/sipAccounts HTTP/1.1
Host: api.ymcs.yealink.com
Content-Type: application/json

{
  "registerName": "2552",
  "username": "2552",
  "password": "******",
  "label": "2552",
  "displayName": "2552",
  "sipServer1": {
    "host": "ume.yealink.com",
    "port": 5061
  }
}

PacketDial Integration Example

For provisioning to PacketDial/NetSapiens PBX:

{
  "registerName": "100@vwp.91912.service",
  "username": "100@vwp.91912.service",
  "password": "TestPass123",
  "label": "Extension 100",
  "displayName": "Test User",
  "sipServer1": {
    "host": "pbx.packetdial.com",
    "port": 5060
  }
}

HTTP 412 Error Resolution

Error: HTTP 412: {"code": "900444", "details": [{"field": "sipServer1", "message": "Parameter error, please refer to documentation related to interface parameters"}]}

Cause: Passing sipServer1 as a string instead of an object

Fix: Use the SipServer object format with both host and port fields

Response (201 Created)

{
  "id": "604e67944c7c43fe8b66099254ec3439",
  "username": "2552",
  "registerInfo": "2552",
  "serverAddress": "ume.yealink.com:5061",
  "accountType": 0,
  "remark": "",
  "createTime": 1234567890000
}

Response fields:

• id: Account ID (use for binding to devices)
• accountType: 0=SIP, 1=H323, 2=SFB
• serverAddress: Combined host:port from sipServer1
• createTime: Unix timestamp in milliseconds

Next Step: Bind Account to Device

After creating the SIP account, bind it to a phone:

POST /v2/dm/devices/{deviceId}/bindAccounts

Body:

{
  "accountIds": ["604e67944c7c43fe8b66099254ec3439"],
  "lineId": 1
}

See chunk-03 pages 52-56 for bindAccounts endpoint details.