YimaPass
Sign In Sign Up

API Documentation

BASEURL
https://api.yimatongsms.com

Create Order

GET /api/order/createOrder

Request

Parameter Type Required Remark
secretKey str Yes API Key
smsCountryId int Yes Country service ID (smsCountryId from catalog)
buyNum int Yes Quantity (required). Must be at least the minimum purchase quantity shown in the catalog (typically 1; some products may require more).

Response

Parameter Type Remark
code int Code: 0=success (including queryOrder while processing); 400=business failure; 401=createOrder invalid secretKey only; 404=not found; 429=rate limited; 500=internal error
message str Message
data.apiOrderId str Order ID
Success Example 
{
  "code": 0,
  "message": "创建成功",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721" }
}
Error Example 
{
  "code": 401,
  "message": "密钥无效或缺失",
  "data": null
}
More examples: createOrder — processing (still code=0) 
{
  "code": 0,
  "message": "处理中，请稍后查询",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721" }
}
More examples: createOrder — 401 invalid secretKey 
{
  "code": 401,
  "message": "密钥无效或缺失",
  "data": null
}
More examples: createOrder — 404 invalid country service 
{
  "code": 404,
  "message": "国家服务不存在或已停用",
  "data": null
}
More examples: createOrder — 400 insufficient balance 
{
  "code": 400,
  "message": "余额不足",
  "data": null
}
More examples: createOrder — 500 create failed 
{
  "code": 500,
  "message": "创建失败",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721" }
}

Query Order

GET /api/order/queryOrder

Request

Parameter Type Required Remark
apiOrderId str Yes Order ID

Response

Parameter Type Remark
code int Code: 0=success (including queryOrder while processing); 400=business failure; 401=createOrder invalid secretKey only; 404=not found; 429=rate limited; 500=internal error
message str Message
data.apiOrderId str Order ID
data.contents json(list) Fixed contents list format, each item is one order content row

data item fields

Parameter Type Remark
data.contents[].contentId string Content row ID; use as resolveNumber contentId param
data.contents[].type int 1=text row, 2=row with getdata link
data.contents[].content string Row content string
data.contents[].expiresAt string Suggested deadline to fetch the SMS code (ISO-8601 local time, e.g. 2026-05-28T15:04:00). After this time the number may no longer return a code.
Success Example 
{
  "code": 0,
  "message": "查询成功",
  "data": {
    "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721",
    "contents": [
      { "contentId": "806779395c1640c882e65aaf1aba21d9", "type": 2, "content": "13800138000----/api/order/getdata?contentId=806779395c1640c882e65aaf1aba21d9", "expiresAt": "2026-05-28T15:04:00" },
      { "contentId": "a1b2c3d4e5f6", "type": 2, "content": "13900139000----/api/order/getdata?contentId=a1b2c3d4e5f6", "expiresAt": "2026-05-28T15:08:00" }
    ]
  }
}
Error Example 
{
  "code": 404,
  "message": "订单不存在或无权限",
  "data": { "apiOrderId": "not-exists-order-id" }
}
More examples: queryOrder — processing (code=0) 
{
  "code": 0,
  "message": "处理中，请稍后查询",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721", "contents": [] }
}
More examples: queryOrder — 404 order not found 
{
  "code": 404,
  "message": "订单不存在或无权限",
  "data": { "apiOrderId": "not-exists-order-id" }
}

Release number

GET /api/order/resolveNumber

Release numbers in an order (no secretKey). GET BASEURL + /api/order/resolveNumber?apiOrderId=...; optional contentId (contents[].contentId from queryOrder) releases one row, omit to try all unreleased rows without SMS. Rows that already received SMS cannot be released. Success message includes refund info; code=400 on failure (retryable). Unsupported order types also return 400.

Request

Parameter Type Required Remark
apiOrderId str Yes Order ID
contentId str optional Optional. data.contents[].contentId from queryOrder; releases only that row when set

Response

Parameter Type Remark
code int Code: 0=success (including queryOrder while processing); 400=business failure; 401=createOrder invalid secretKey only; 404=not found; 429=rate limited; 500=internal error
message str Message
data.apiOrderId str Order ID
Success Example 
{
  "code": 0,
  "message": "已释放，退 0.050 USD",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721" }
}
Error Example 
{
  "code": 400,
  "message": "号码已收到短信，无法释放",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721" }
}
More examples: resolveNumber — 400 already has SMS 
{
  "code": 400,
  "message": "号码已收到短信，无法释放",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721" }
}
More examples: resolveNumber — 404 order not found 
{
  "code": 404,
  "message": "订单不存在或无权限",
  "data": { "apiOrderId": "not-exists-order-id" }
}

Get Data

GET /api/order/getdata

Usage: call /queryOrder first. For type=2 rows, call BASEURL + /api/order/getdata?contentId=... Response: plain text only.

Request

Parameter Type Required Remark
contentId str Yes Extract contentId from /api/order/getdata?contentId=...

Response

HTTP status Body example Meaning
200 123456 Success; plain-text body (e.g. SMS code)
400 invalid contentId Invalid contentId
404 not found Content not found or not permitted
429 Too Many Requests Rate limited
502 fetch error Failed to fetch content
Success Example 
123456
Error Example 
not found
More examples: getdata — 429 rate limited 
Too Many Requests

Frequently Asked Questions (FAQ)

Q1. What is the data structure of queryOrder?

data is an object with apiOrderId and contents. Each row has contentId, type, and content; SMS verification orders also include expiresAt. contentId is the optional resolveNumber parameter.

Q2. How do I access getdata content?

When type=2, extract contentId and call /api/order/getdata?contentId=... (plain text body).

Q3. What format does getdata return?

getdata returns plain text without a JSON wrapper.

Q4. Does createOrder return code=202?

No. Both createOrder and queryOrder while stocking return code=0. Use message (e.g. processing hint) and whether contents is empty; poll queryOrder.

Q5. What unit are balances and charges in?

Account balance, unit price, and order totals are USD (up to 3 decimal places). Refund amounts in API messages use USD too, e.g. "已释放，退 0.050 USD".