DescribePhoneNumberOperatorAttribute-阿里云帮助中心

Queries the carrier information of a phone number, including the province, city, basic carrier (China Mobile, China Unicom, China Telecom, or China Broadnet), mobile virtual network operator (such as Alibaba Cloud Communication), whether the number has been ported, and the number segment.

Operation description

Before you use this API, make sure that you are familiar with the billing of Cell Phone Number Service.
By default, only Alibaba Cloud accounts can use this API. RAM users can use this API only after they are granted the required permissions. For more information, see Grant permissions to a RAM user.
This API is used to obtain the current carrier, location, and number portability information of a phone number. The API supports queries for plaintext, MD5, and SHA256 encrypted phone numbers.
Before you use this API, log on to the Cell Phone Number Service console, go to the Tag Square page, find the corresponding tag, click Apply for Activation, and submit the application materials. You can use the API after your application is approved.

QPS limit

The QPS limit per user for this API is 2,000 calls per second. If the limit is exceeded, API calls are throttled, which may affect your business. Make calls reasonably.

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 that you want to query. If Mask is set to NORMAL, this field is an 11-digit phone number. If Mask is set to MD5, this field is a 32-character encrypted string. If Mask is set to SHA256, this field is a 64-character encrypted string. If Mask is set to SM3, this field is a 64-character 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 of the Cell Phone Number Service console, obtain the authorization ID, which 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 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 returned data.
AccessDeniedDetail	string	The details about the access denial. This parameter is returned only if the request is denied because the RAM user or RAM role does not have the required permissions.	-
Message	string	The description of the status code.	OK
RequestId	string	The request ID.	68A40250-50CD-034C-B728-0BD135850177
Data	object	The returned data.
BasicCarrier	string	The basic carrier. Valid values: China Mobile. China Unicom. China Telecom. China Broadnet.	China Mobile
NumberSegment	integer	The number segment to which the phone number belongs.	139
IsNumberPortability	boolean	Indicates whether the number has been ported. Valid values: true: yes false: no	false
Carrier	string	The actual carrier (including the mobile virtual network operator). If number portability is enabled, the value indicates the carrier after number portability.	China Mobile
City	string	The city to which the phone number belongs.	Hangzhou
Province	string	The province to which the phone number belongs.	Zhejiang
Code	string	The status code of the request. Valid values: OK: The request is successful. InvalidParameter: The phone number is invalid or the format of the parameter is invalid. PhoneNumberNotfound: The carrier information of the phone number is not found. isp.UNKNOWN: An unknown error occurred. RequestFrequencyLimit: Due to carrier restrictions, you cannot frequently query the same number in a short period of time. If this error code is returned, try again later.	OK

Causes of status codes and solutions

Status code	Cause	Solution
OK: The request is successful.	The request parameters meet the requirements.	The API call is successful.
InvalidParameter: The phone number is invalid or the format of the parameter is invalid.	The format of the phone number in the request parameter is invalid, or the request parameter does not meet the requirements of the API.	Enter a correct phone number or adjust the format of the request parameter, and then resubmit the request. For example, remove invisible characters and spaces from the phone number, or change full-width characters to half-width characters.
PhoneNumberNotfound: The carrier information of the phone number is not found.	The carrier information of the phone number is not found.	Use another phone number to query.
isp.UNKNOWN: An unknown error occurred.	The system returned an unknown error.	Try to call the API again. We recommend that you do not retry more than three times.

Meanings of the BasicCarrier and Carrier fields

Carrier of the phone number segment	Whether number portability is enabled	Returned result of the BasicCarrier field	Returned result of the Carrier field
Basic carrier number segment	Yes	The basic carrier after number portability (China Mobile, China Unicom, China Telecom, or China Broadnet)	The basic carrier after number portability (China Mobile, China Unicom, China Telecom, or China Broadnet)
Basic carrier number segment	No	Basic carrier (China Mobile, China Unicom, China Telecom, or China Broadnet)	Basic carrier (China Mobile, China Unicom, China Telecom, or China Broadnet)
Virtual carrier number segment	Not supported	Basic carrier (China Mobile, China Unicom, China Telecom, or China Broadnet)	Virtual carrier (such as Alibaba Cloud Communication)

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 Error Codes for a complete list.

Release notes

See Release Notes for a complete list.