DescribePhoneNumberOnlineTime-阿里云帮助中心

Queries the duration for which a mobile user has been registered on the carrier's network.

Operation description

Before using 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, fill in the application materials, and use the API after the application is approved.
Make sure that you fully understand the product pricing of Cell Phone Number Service before using this API.

QPS limit

The per-user QPS limit for this API is 200 calls per second. If the limit is exceeded, API calls are throttled, which may affect your business. 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 Log on to the Cell Phone Number Service console, go to the My Applications page, and obtain the authorization ID, which is the authorization code.	QASDW@#**
InputNumber	string	Yes	The phone number to be queried. 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. Important Letters in the encrypted string are case-insensitive.	1390000****
Mask	string	Yes	The encryption method of the phone number. Valid values: NORMAL: no encryption MD5 SHA256	NORMAL
Carrier	string	No	The external carrier. Valid values: MOBILE: China Mobile. UNICOM: China Unicom. TELECOM: China Telecom. Important This parameter is optional. Alibaba Cloud automatically determines the carrier type based on the phone number. The value of this field has no impact on the query result.	UNICOM

Response elements

Element	Type	Description	Example
	object
RequestId	string	The request ID.	CC3BB6D2-2FDF-4321-9DCE-B38165CE4C47
Code	string	The request status code. Valid values: OK: The request was successful. PortabilityNumberNotSupported: The mobile number portability number is not supported. RequestFrequencyLimit: Due to carrier restrictions, frequent repeated queries on the same number within a short period are prohibited. If this error code is returned, try again later. Note Charges are incurred when Code is OK and VerifyResult is not -1. For billing details, see Cell Phone Number Service Pricing.	OK
Message	string	The description of the number status code.	OK
Data	object	The returned data.
VerifyResult	string	The enumeration value of the network registration duration. Valid values: -1: No duration was found. 0: Abnormal phone status, for example, a non-existent number. 1: [0-3) months. 2: [3-6) months. 3: [6-12) months. 4: [12-24) months. 5: [24,+∞) months.	1
CarrierCode	string	The carrier SMS status code. Valid values: CMCC: China Mobile CUCC: China Unicom CTCC: China Telecom CBN: China Broadnet	CMCC

Causes and solutions for status codes

HttpCode	Status Code	Cause	Solution
200	OK: success.	The request parameters meet the requirements.	Indicates that the API call was successful.
200	PortabilityNumberNotSupported: The number query is not supported.	A small number of mobile number portability numbers return this error code.	We recommend that you query other numbers. The mobile number portability number has been deregistered on the original carrier side, and the new carrier regards the porting time as the account opening time. Therefore, the real status of the mobile number portability number cannot be accurately queried.

Causes and solutions for exceptions

HttpCode	Status Code	Cause	Solution
400	AuthCodeNotExist: The authorization code does not exist.	The authorization code does not exist.	Apply for the required tag in the Cell Phone Number Service. After the application is approved and the authorization code is obtained, call the DescribePhoneNumberOnlineTime API.
400	CarrierIllegal: Invalid carrier type.	Invalid carrier type.	Enter the correct carrier type. For encrypted numbers, this field is required and must be in uppercase.
400	MobileNumberIllegal: Invalid phone number format in the request parameter.	The phone number format is incorrect.	If the phone number is not encrypted, enter 11 correct digits. If the phone number is encrypted with MD5, this field is a 32-character encrypted string. If the phone number is encrypted with SHA256, this field is a 64-character encrypted string.
400	MobileNumberTypeNotMatch: The phone number format does not match the encryption type.	The phone number does not match the encryption type.	Enter the correct phone number format and encryption type.
400	MobileNumberTypeIllegal: Invalid encryption type.	The encryption method is not supported or the encryption type is non-standard.	Only NORMAL, MD5, and SHA256 are supported as encryption methods, and they must be in uppercase.
500	Unknown: Unknown error.	The system returned an unknown error.	Try to call the API again. We recommend that you do not retry more than 3 times.
500	SystemError: Network element system error.	System error.	Try to call the API again. We recommend that you do not retry more than 3 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 Error Codes for a complete list.

Release notes

See Release Notes for a complete list.