Getting started

• Introduction
• API Scope
• Subscribe to the API
• API Authentication
• API Description
  • Summary of resources
  • Summary of methods and URL
  • Verification Operation
    • Request phone number verification
      • Request
      • Fields description
      • Response
      • Fields description
  • Return phone number Operation
    • Request phone number
      • Request
      • Response
      • Fields description
  • Most frequent errors
    • History of document

Introduction

The CAMARA Number Verification API performs real-time checks on the phone number associated to an Orange mobile line on the Orange mobile network. It reveals if the user is using a device with same mobile phone number as it is declared.

API Scope

Current API implementation covers all Orange Spain (Jazztel and ???) mobile lines.

Subscribe to the API

You get the Authorization header credentials when you register your application on the Orange Developer Console.

API Authentication

HTTPS requests to the REST API are protected with 3-Legged OAuth. In short, this API uses Authorization by code (aka three-legged OAuth) mechanism as the final user of the service is requested to give their consent in order to authorize this client application to access their resources.

Step 1: request the OAuth authorization code from the user device

To authenticate the end-user and obtain her/his consent a GET request must be sent to the authorize endpoint from the user device. This request must provide required parameters.

curl -X GET "https://api.partner.com/camara/oes/number-verification/v0/authorize?client_id={client_id}&response_type=code&redirect_uri={redirect_uri}&scope=dpv%3AFraudPreventionAndDetection%23number-verification-verify-read"

Once the end-user provided her/his consent, the Orange authorization server will send back to the client application an authorization code.

Step 2: Request the OAuth access token

Once the client application got the authorization code, it has to get the access token protecting the resoures. In order to retrieve it, the client application triggers a POST request to the token endpoint.

curl -X POST "https://api.partner.com/es/openapi/oauth/v2/token"
-H "Authorization: Basic {your application Basic header}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code&code={code}&redirect_uri={redirect_uri}"

If the transaction succeeds, in the POST response, the acccess_token is provided.

Step 3: Access protected resources using OAuth access token

In order to call our API, the access_token is mandatory.

Specific documentation about number Verification resources is provided below.

Go up

API Description

Summary of resources

This API has two resource Verification and device-phone-number

Summary of methods and URL

Go up

Verification Operation

Verifies if provided phone number (plain text or hashed format) matches the one that the user is currently using. The API returns true/false depending on if the input matches the authenticated user's device phone number associated to the access token.

Go up

Request phone number verification

Request

Using plain text phone number:

curl -X POST "https://api.partner.com/camara/oes/number-verification/v0/verify"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  '{
"phoneNumberType": "RegularPhoneNumber",
"phoneNumber": "33612345678"
}

Using hashed phone number:

curl -X POST "https://api.partner.com/camara/oes/number-verification/v0/verify"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  '{
"phoneNumberType": "HashedPhoneNumber",
"phoneNumber": "32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba"
}

Fields description

As the request could be done with a plain text or a hashed phone number, it is requested to provide phoneNumberType attribute to specify phone number format

2 values for phoneNumberType are managed:

• RegularPhoneNumber or REGULAR - in this case the phone number must be pass in E.164 format (starting with country code). Optionally prefixed with '+'.
• HashedPhoneNumber or HASHED - in this case the Hashed phone number must be a SHA-256 (in hexadecimal representation) of the mobile phone number in E.164 format (starting with country code)

Depending on this type, the second attribute phoneNumber must be valued accordingly.

Response

200 
Content-Type: application/json
{
  "devicePhoneNumberVerified": true
}

Go up

Fields description

The response features only one attribute: devicePhoneNumberVerified.

This attribute is boolean indicating if a phone number provided correspond to the one associated with the access token.

Go up

Return phone number Operation

Returns the phone number associated with the access token so the API clients can Verification the number themselves.

Go up

Request phone number

Request

curl -X GET "https://api.partner.com/camara/oes/number-verification/v0/device-phone-number"
-H "Authorization: Bearer {your access token}" 
-H 'accept: application/json'

Response

200 
Content-Type: application/json
{
    "devicePhoneNumber": {
        "phoneNumberType": "REGULAR",
        "phoneNumber": "+33612345678"
    }
}

Go up

Fields description

The response features devicePhoneNumber structure with two attributes: phoneNumberType to specify if the phone number value is a plain text or a hash, and phoneNumber which is the value itself.

Go up

Most frequent errors

Most frequent errors for this API are related to insufficient permission (code 403). In addition to regular scenario of PERMISSION_DENIED, other scenarios may exist:

• Client authentication was not performed via mobile network. In order to check the authentication method, AMR parameter value in the 3-legged user's access token can be used and make sure that the authentication was not either by SMS+OTP nor username/password ({"code": "NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK","message": "Client must authenticate via the mobile network to use this service"})
• Phone number cannot be deducted from access token context.({"code": "NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT","message": "Phone number cannot be deducted from access token context"})

Permission denied:

HTTP/1.1 403 Error: bad Request
Content-Type: application/json
{
  "code": "PERMISSION_DENIED",
  "status": "403",
  "message": "Client does not have sufficient permissions to perform this action"
}

User not authenticated by Orange mobile network:

HTTP/1.1 403 Error: bad Request
Content-Type: application/json
{
  "status": 403,
  "code": "NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK",
  "message": "Client must authenticate via the mobile network to use this service"
}

Invalid access token:

HTTP/1.1 403 Error: bad Request
Content-Type: application/json
{
  "status": 403,
  "code": "NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT",
  "message": "Phone number cannot be deducted from access token context"
}

There are some cases where your client application will no longer gain access to API resources, and get an error back.

Please check the following points:

• Here, you attempt to use an expired or revoked access_token and you get an invalid token error. You will have to request a new access_token. As an example:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
  "code": "UNAUTHORIZED",
  "message": "Authorization failed: ..."
}

Go up

History of document

Go up