DescribePhoneNumberOnlineTime-阿里云帮助中心

Queries how long a mobile number has been in service with its carrier.

Operation description

Before you call this operation, log on to the Cell Phone Number Service console. On the Label Plaza page, find the required label, click Request, complete the application, and wait for approval.
Before you call this operation, review the pricing for Cell Phone Number Service.

QPS limits

The queries per second (QPS) limit for a single user is 200. If you exceed this limit, API calls are throttled, which may affect your business. We recommend that you 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:DescribePhoneNumberOnlineTime

create

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
AuthCode	string	Yes	The authorization code. Note In the Cell Phone Number Service console, go to the My Approvals page to obtain the authorization ID. Use this ID as the authorization code.	QASDW@#**
InputNumber	string	Yes	The number to query. If you set Mask to NORMAL, this parameter is an 11-digit mobile phone number. If you set Mask to MD5, this parameter is a 32-bit encrypted string. If you set Mask to SHA256, this parameter is a 64-bit encrypted string. Important The letters in the encrypted string are not case-sensitive.	1390000****
Mask	string	Yes	The encryption method of the number. Valid values: NORMAL: The number is not encrypted. MD5 SHA256	NORMAL
Carrier	string	No	The carrier. Valid values: MOBILE: China Mobile. UNICOM: China Unicom. TELECOM: China Telecom. Important This parameter is optional. Alibaba Cloud automatically determines the carrier based on the number. The value of this parameter does not affect the query result.	UNICOM

Response elements

Element	Type	Description	Example
	object
RequestId	string	The request ID.	CC3BB6D2-2FDF-4321-9DCE-B38165CE4C47
Code	string	The status code of the request. Valid values: OK: The request is successful. PortabilityNumberNotSupported: The mobile number portability service is not supported for the number. RequestFrequencyLimit: Due to carrier restrictions, you cannot frequently query the same number in a short period. If this error code is returned, try again later. Note Billing is triggered when the value of Code is OK and the value of VerifyResult is not -1. For more information about billing, see pricing for Cell Phone Number Service.	OK
Message	string	The description of the status code.	OK
Data	object	The returned data.
VerifyResult	string	An enumerated value that indicates how long a mobile number has been in service. Valid values: -1: The duration cannot be found. 0: The phone number is in an abnormal state, such as a nonexistent number. 1: 0 to 3 months. 2: 3 to 6 months. 3: 6 to 12 months. 4: 12 to 24 months. 5: 24 months or more.	1
CarrierCode	string	The carrier code. Valid values: CMCC: China Mobile CUCC: China Unicom CTCC: China Telecom CBN: China Broadnet	CMCC

Status codes

HTTP status code	Error code	Cause	Solution
200	OK: The request is successful.	The request parameters meet the requirements.	The API call is successful.
200	PortabilityNumberNotSupported: The number query is not supported.	This error code is returned for a small number of mobile numbers that have been ported.	Query a different number. When a number is ported, it is deactivated with the original carrier. The new carrier considers the port-in date as the activation date. Therefore, the actual status of a ported number cannot be accurately queried.

Errors

HTTP status code	Error code	Cause	Solution
400	AuthCodeNotExist: The authorization code does not exist.	The authorization code does not exist.	Request the required label in the Cell Phone Number Service console. After your request is approved and you obtain an authorization code, retry the call to the DescribePhoneNumberOnlineTime operation.
400	CarrierIllegal: The carrier type is invalid.	The carrier type is invalid.	Enter a valid carrier type. For encrypted numbers, this parameter is required and its value must be in uppercase.
400	MobileNumberIllegal: The format of the mobile phone number is invalid.	The format of the mobile phone number is invalid.	If the number is not encrypted, enter a valid 11-digit number. If the number is MD5 encrypted, enter a 32-bit encrypted string. If the number is SHA256 encrypted, enter a 64-bit encrypted string.
400	MobileNumberTypeNotMatch: The mobile phone number format does not match the encryption type.	The entered mobile phone number does not match the encryption type.	Enter a mobile phone number in the correct format and specify the correct encryption type.
400	MobileNumberTypeIllegal: The encryption type is invalid.	The specified encryption method is not supported or the encryption type is not in the standard format.	Specify a valid encryption type. Valid values are NORMAL, MD5, and SHA256. The value must be in uppercase.
500	Unknown: An unknown error occurred.	The system returned an unknown error.	Retry the call. Do not retry more than three times.
500	SystemError: A network element system error occurred.	A network element system error occurred.	Retry the call. Do not retry more than three times.

Examples

Success response

JSON format

{
  "RequestId": "CC3BB6D2-2FDF-4321-9DCE-B38165CE4C47",
  "Code": "OK",
  "Message": "OK",
  "Data": {
    "VerifyResult": "1",
    "CarrierCode": "CMCC"
  }
}

Error codes

HTTP status code	Error code	Error message	Description
200	PortabilityNumberNotSupported	Number portability is not supported
400	Insufficient.Balance	You have an insufficient balance.	Your account does not have sufficient balance.
400	Product.Unsubscript	You have not subscribed to the specified product.
400	Ram.PermissionDeny	You are not authorized to perform the operation.
400	System.LimitControl	The system is under flow control.
400	Unknown.ResourceOwnerId	The resource does not belong to the current user.
400	AuthCodeNotExist	Authorization code does not exist
400	CarrierIllegal	Illegal carrier type
400	MobileNumberIllegal	Wrong format of phone number
400	MobileNumberTypeNotMatch	Phone number and encryption type do not match
400	MobileNumberTypeIllegal	Invalid number type.
400	InvalidParameter	Invalid parameter.
400	AuthCodeIllegal	Illegal authCode.
500	SystemError	System error
500	Unknown	Unknown error
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.