Getting started

• Introduction
• API Scope
• Subscribe to the API
• API Authentication
• API Description
  • Summary of resources
  • Summary of methods and URL
  • Verify 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 with an Orange mobile line on the Orange mobile network. It reveals if the user is using a device with the same mobile phone number as the one which is declared.

API Scope

The current API implementation covers all Orange France 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. To learn more about how Orange Developer handles authentication, please refer to our documentation.

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 as described in Orange tech guide referred above. It is mandatory to provide a scope in this request. Orange implementation follows the CAMARA scope definition. The scope must be set to: dpv:<dpvValue>#<technicalParameter>. dpv stands for Data Privacy Vocabulary.

For the current implementation only FraudDetectionAndPrevention dpv value is managed which means that:

• to check the msisdn, the scope in the authorizemust be set to the individual scope dpv:FraudPreventionAndDetection#number-verification:verify
• to obtain the msisdn, the scope in the authorize must be set to the individual scope dpv:FraudPreventionAndDetection#number-verification:device-phone-number:read

Please note that a global scope dpv:FraudPreventionAndDetection#number-verification is also defined and gives access to all resources.

Once the end-user provides her/his consent, the Orange authorization server returns 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 resources. In order to retrieve it, the client application triggers a POST request to the token endpoint.

Like for previous steps, detailed attribute prerequisites are described in the Orange tech guide.

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.

API Description

Summary of resources

This Number Verification API has two resources verify and device-phone-number

Summary of methods and URL

Verify Operation

Verifies if the 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 with the access token.

Request phone number verification

Request

Using plain text phone number:

curl -X POST "https://api.orange.com/camara/ofr/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  '{
"phoneNumber": "+33612345678"
}

Using hashed phone number:

curl -X POST "https://api.orange.com/camara/ofr/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  '{
"hashedPhoneNumber": "32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba"
}

Fields description

• Regular phoneNumber (phoneNumber) must be passed in E.164 format (starting with country code). Prefixed with '+'.
• Hashed phoneNumber (hashedPhoneNumber) must be a SHA-256 (in hexadecimal representation) of the mobile phone number in E.164 format (starting with country code and prefixed with +)

Response

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

Fields description

The response features only one attribute: devicePhoneNumberVerified.

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

Return phone number Operation

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

Request phone number

Request

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

Response

200 
Content-Type: application/json
{
    "devicePhoneNumber": "+33612345678"
}

Fields description

The response features devicePhoneNumber - In order to be globally unique it is formatted in international format, according to E.164 standard, prefixed with '+'.

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 back an error.

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