Get Number Profile

The Number Profile operation is a lookup service for obtaining information about an end user's phone number, such as the device make and model information.

This is particularly useful in MMS transaction flows where content-device compatibility is important. For example, this operation can identify iPhones on the AT&T network.

Quick facts

Method	GET
Returns	XML in synchronous response
Available	United States with AT&T.
Prerequisites	You must have number profile lookups provisioned with OpenMarket.

Making a Request

 

Path parameters

Parameter	Description
phoneNumber	The phone number, including US country code, of the end user's device. Used as the destination address in a transaction. For example: 12515550145. Required: yes Type: integer

Query parameters

Parameter	Description
types	Type of profile information to be returned. Accepted values: DEVICE, BILLABLE, PREPAID, DEACT, ALL. Required: yes Type: string
carrierId	A numeric ID representing the mobile operator as known by OpenMarket. This is 383 for AT&T. If you don't specify this, OpenMarket will look up the ID using the phone number. You may be charged for this lookup. Required: no Type: integer
timeout	Maximum time in milliseconds to process the request. You can set this to between 1 to 30000 (30 seconds). Required: no Type: long

Header fields

You must provide your authentication details using Basic authentication in the header. For example:

Field	Description
Authorization	Your account ID and password, separated by a colon, and then base64 encoded. Your account ID and password are case-sensitive. For help with Basic authentication see Authenticate with OpenMarket.

Response from OpenMarket

Accepted requests

OpenMarket responses to successful requests with an HTTP 200 status code and the details of the end user's device as XML in the response body.

Response header

The response header will include following data.

Field	Description
X-Request-Id	A unique ID that identifies the specific request in OpenMarket's systems. This ID is logged in our systems and is useful if you need to query the request with OpenMarket Support at a later date. Type: A string of 1 to 32 characters in length. Returned: Always
Content-Type	Identifies that the request contains XML in the request body. Returned: Always

Response body

The XML response body will include following data.

Elements / attributes	Description
number	Root element. Contains two elements: carrier and device. Returned: Always
xmlns	The XML namespace. Type: string Returned: Always
schemaVersion	The response schema version number for the return value. Type: string Returned: Always
phoneNumber	The phone number you provided. Type: string Returned: Always
carrier	Mobile operator element. This identifies the mobile operator for the phone number. Returned: Always
id	The mobile operator ID, which for AT&T is 383. Type: integer Returned: Always
device	Information about the device. This element has these attributes: model, make and passthroughData. Returned: Always
model	Type of mobile phone model. For example, "IPHONE 4S WHITE 32GB". Type: string Returned: Always
make	The manufacturer of the phone. For example, "APL" for Apple. Type: string Returned: Always
passthroughData	Optional data passed through from the mobile operator, such as the raw phoneID, uaProf, or uaString. For example, "CMD-8500". Type: string Returned: If provided by operator

Rejected requests

If your request is rejected then the body of the response will contain a code that identifies the error. For example:

Response header

The response header will include following data.

Field	Description
X-Request-Id	A unique ID that identifies the specific request in OpenMarket's systems. This ID is logged in our systems and is useful if you need to query the request with OpenMarket Support at a later date. Type: A string of 1 to 32 characters in length. Returned: Always
Content-Type	Identifies that the request contains XML in the request body. Returned: Always

Response body

The XML response body will include following data.

Elements / attributes	Description
errors	Root element. Contains the errorelement. Returned: Always
xmlns	The XML namespace. Type: string Returned: Always
schemaVersion	The response schema version number for the return value. Type: string Returned: Always
error	Error element. Returned: Always
code	Code defining the reason for the outcome of the request. For a list of the codes, see Response error codes below. Type: integer Returned: Always
description	Natural language description of the error. Type: string Returned: Always

Testing your integration

You can test this operations directly against the production environment; however, this means you will be making real requests sent to the mobile operators. Therefore to test your integration, we suggest the following:

• Use test phones that are only connected to AT&T.
• Ensure that you pass in the mobile operator ID in your requests unless you are testing our response to this.

Contact us if you'd like more information on testing options.

Troubleshooting

Response error codes

These codes are returned in the response body when there was a problem with receiving the request.

Search for a code or any part of a description:

OpenMarket code	Description
420	Invalid Account ID or Password. Ensure that you have correctly encoded your username and password.
1000	System error: General error occurred while processing request. Do not retry the request.
1020	Temporary external system error. You can retry these requests. If retries fail beyond the recommended retry period please contact OpenMarket Support for assistance troubleshooting.
6500	Invalid request or resource not found. Returned if we received the request but the URL it was sent to doesn't correctly identify the API.
6501	Account not enabled for service.
6502	Invalid request - Invalid phone number. The phone number specified in the URL is either missing or incorrectly formatted. It must be a US phone number and include the country code, for example: 12515550130.
6503	Unable to determine carrierId. You can receive this if you did not include carrierId in your request and we performed an operator lookup. This indicates that there was no mobile operator found for the number.
6504	Carrier not supported.
6505	Phone number not found with carrier. The phone number is not registered with that carrier.
6509	Invalid request - HTTP method is not allowed. You can only use GET requests to this endpoint.
6510	Invalid request - Not a valid API version: You would receive this only if you specified the URL incorrectly and somehow had "v4" or another number instead of "v1" in the URL: https://numpro.openmarket.com/numpro/v1/number/
6511	Invalid request - Unsupported query parameter. Unable to parse the parameter. Check documentation for accepted values.
6512	Invalid request - Invalid carrierId. The carrierId field returned a NaN value.
6513	Invalid request - Invalid types. Unable to parse the types parameter Check the spelling or review types for the list of accepted values.
6514	No device info found. We sent a request to the mobile operator, however their response did not include any device information.
6515	Invalid request - Missing types. We've checked the data type of each parameter whether it is required or not. See types for the list of accepted arguments.
6520	Permission denied to external system. This is returned if your request excluded carrierId and your account is not provisioned for operator lookups. You must supply the carrierId if you are not provisioned for operator lookups.
6522	Response exceeded maximum timeout.
6524	Account not enabled for infoTypes (list of infoTypes). Your account has not been provisioned to use this operation. Contact your OpenMarket account manager.