DescribePhoneNumberOperatorAttribute-阿里云帮助中心

Queries the attribute information of a mobile phone number. This includes the province, city, basic carrier (China Mobile, China Unicom, China Telecom, or China Broadnet), mobile virtual network operator (MVNO) such as Alibaba Communications, mobile number portability (MNP) status, and number segment.

Operation description

Before you call this API, make sure that you understand the billing of Cell Phone Number Service.
By default, only Alibaba Cloud accounts can call this API. Resource Access Management (RAM) users can call this API only after they are granted the required permissions. For more information, see Grant permissions to RAM users.
This API is used to obtain the current service carrier, location, and mobile number portability information of a phone number. It supports queries for phone numbers in plaintext or encrypted with MD5 or SHA256.
Before you use this API, log on to the Cell Phone Number Service console. On the Tag Square page, find the required tag, click Request Access, and then fill in the application form. You can use the service after your application is approved.

QPS limits

The queries per second (QPS) limit for a single user is 2,000 calls/second. If you exceed this limit, API calls are throttled, which may affect your services. To avoid service interruptions, call this API at a reasonable rate.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

dytns:DescribePhoneNumberOperatorAttribute

get

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
InputNumber	string	Yes	The phone number to query. If Mask is set to NORMAL, this parameter specifies an 11-digit phone number. If Mask is set to MD5, this parameter specifies a 32-bit encrypted string. If Mask is set to SHA256, this parameter specifies a 64-bit encrypted string. If Mask is set to SM3, this parameter specifies a 64-bit encrypted string. Important The letters in the encrypted string are not case-sensitive.	139****1234
AuthCode	string	Yes	The authorization code. Note On the My Applications page in the Cell Phone Number Service console, obtain the authorization ID. The authorization ID is the authorization code.	Dd1r***4id
Mask	string	Yes	The encryption method of the phone number. Valid values: NORMAL: No encryption MD5: MD5 encryption SHA256: SHA256 encryption SM3: SM3 encryption Important All letters in the string must be in uppercase.	MD5
FlowName	string	No	A system parameter. You do not need to specify this parameter.	-
ResultCount	string	No	A system parameter. You do not need to specify this parameter.	-

Response elements

Element	Type	Description	Example
	object	The data returned.
AccessDeniedDetail	string	The details of the access denial. This parameter is returned only when RAM authentication fails.	-
Message	string	The description of the status code.	OK
RequestId	string	The request ID.	68A40250-50CD-034C-B728-0BD135850177
Data	object	The struct.
BasicCarrier	string	The basic carrier. Valid values: China Mobile. China Unicom. China Telecom. China Broadnet.	中国移动
NumberSegment	integer	The number segment.	139
IsNumberPortability	boolean	Indicates whether the number has been ported. Valid values: true: Yes false: No	false
Carrier	string	The actual carrier, including virtual carriers. If the number has been ported, this is the carrier after porting.	中国移动
City	string	The city where the number is registered.	杭州
Province	string	The province where the number is registered.	浙江
Code	string	The status code of the request. Valid values: OK: The request was successful. InvalidParameter: The specified phone number is invalid or the parameter format is incorrect. PhoneNumberNotfound: The attribution information for the specified phone number cannot be found. isp.UNKNOWN: An unknown error occurred. RequestFrequencyLimit: Due to carrier restrictions, frequent queries for the same number within a short period of time are prohibited. If this error code is returned, try again later.	OK

Causes and solutions for status codes

Status code	Cause	Solution
OK: The request was successful.	The request parameters meet the requirements.	The API call was successful.
InvalidParameter: The specified phone number is invalid or the parameter format is incorrect.	The format of the phone number in the request is incorrect, or the request parameters do not meet the API requirements.	Enter a valid phone number or adjust the format of the request parameters, and then resubmit the request. For example, remove invisible characters or spaces from the phone number, or use half-width characters.
PhoneNumberNotfound: The attribute information for the specified phone number cannot be found.	The attribute information for the specified phone number cannot be found.	Query a different phone number.
isp.UNKNOWN: An unknown error occurred.	The system returned an unknown error.	Retry the API call. Do not retry more than three times.

Meanings of the BasicCarrier and Carrier fields

Number segment attribution	Mobile number portability status	Value of the BasicCarrier field	Value of the Carrier field
Basic carrier number segment	Yes	The basic carrier after porting (China Mobile, China Unicom, China Telecom, or China Broadnet)	The basic carrier after porting (China Mobile, China Unicom, China Telecom, or China Broadnet)
Basic carrier number segment	No	The basic carrier (China Mobile, China Unicom, China Telecom, or China Broadnet)	The basic carrier (China Mobile, China Unicom, China Telecom, or China Broadnet)
Virtual carrier number segment	Not supported	The basic carrier (China Mobile, China Unicom, China Telecom, or China Broadnet)	The virtual carrier (for example, Alibaba Communications)

Examples

Success response

JSON format

{
  "AccessDeniedDetail": "-",
  "Message": "OK",
  "RequestId": "68A40250-50CD-034C-B728-0BD135850177",
  "Data": {
    "BasicCarrier": "中国移动",
    "NumberSegment": 139,
    "IsNumberPortability": false,
    "Carrier": "中国移动",
    "City": "杭州",
    "Province": "浙江"
  },
  "Code": "OK"
}

Error codes

HTTP status code	Error code	Error message	Description
400	EncyrptTypeIllegal	The encryption type of the mobile phone number is illegal
400	InvalidParameter	The specified mobile phone number is invalid.	Invalid Phone Number
400	PhoneNumberNotfound	The queried number is not found.
400	MobileNumberTypeNotMatch	The number and number type do not match.
400	AuthCodeNotExist	The authorization code application failed and cannot be used.	Failed to apply for an authorization code.
400	MobileNumberIllegal	Wrong format of phone number
400	AuthCodeIllegal	Illegal authCode.
500	InternalError	A system error occurred.
500	RequestTimeout	Request supplier timed out.	Request supplier timeout
500	RequestSupplierError	Request supplier error.	Request supplier error.

See for a complete list.

Release notes

See Release Notes for a complete list.