Getting started

• Introduction
  • Subscribe to the API
  • API Authentication
  • API Description
    • Summary of resources
    • Summary of methods and URL
    • Summary of request body parameters
      • Request
      • Response
      • Fields description
    • Most frequent errors
• Looking for support ?
• History of document

Introduction

The CAMARA KYC Match API provides a standardized mechanism to customer with the ability to compare the information it (Service Provider, SP) has for a particular user with that on file (and verified) by the user's Operator in their own KYC records, in order for the SP to confirm the accuracy of the information and provide a specific service to the user

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] (https://developer.orange.com/myapps).

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 supported scopes are:

• openid
• dpv:FraudPreventionAndDetection
• kyc-match:match

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.

Go up

Summary of resources

This API has one resource match. MatchResult attribute provides in the response information about mobile equipment location check.

Summary of methods and URL

Go up

Summary of request body parameters

In bold parameters currently available in Orange France API

Summary of response parameters

In bold parameters currently available in Orange France API

Go up

Request

curl -X POST "https://api.orange.com/camara/ofr/kyc-match/v0/match"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  {
    "phoneNumber": "33699901031",
    "giventName": "Maeva",
    "familyName": "Hurt",
    "locality": "Pottrnec",
    "email": "laure84@voila.fr3"
    "gender": "FEMALE",
}

Response

200 Match successful
Content-Type: application/json

{
    "giventNameMatch": "True",
    "familyNameMatch": "False",
    "familyNameMatchScore": 90,
    "addressMatch": "True",
    "localityMatch": "False",
    "localityMatchScore": 95,
    "emailMatch": "True"
}

Go up

Fields description

The response contains

• MatchResult attributes valued to true when user's information matches exactely with information held by the MNO, false when it doesn't match exactly or not_available when the MNO doesn't hold user's information.
• MatchScore, a numerical value that quantifies the similarity between two pieces of text based on the words they contain for some MatchResult attributes in case of value is equal to false.

Most frequent errors

If invalid input are provided in particular for the device identifier a 400 error is triggered.

HTTP/1.1 400 Invalid input
Content-Type: application/json
{
  "code": "INVALID_ARGUMENT",
  "status": 400,
  "message": "Invalid input"
}

If the network back end is not able to localize the equipment, a 404 error is sent.

HTTP/1.1 404 Not Found
Content-Type: application/json
{
  "status": 404,
  "code": "NOT_FOUND",
  "message": "Unknown Location"
}

If the localisation service is not up and running, a 503 error is sent.

HTTP/1.1 503 Service unavailable
Content-Type: application/json
{
  "code": "UNAVAILABLE",
  "status": 503,
  "message": "Service unavailable"
}

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": "UNAUTHENTICATED",
  "status": 401,
  "message": "Authorization failed: ..."
}

• Here, you removed your subscription to the API so that the capability to generate an access_token is not allowed anymore. As an example:

HTTP/1.1 403 Forbidden
Content-Type: application/json
{
  "code": "PERMISSION_DENIED",
  "status": 403,
  "message": "Operation not allowed: ..."
}

Looking for support ?

Facing technical issue when using this API ? please contact us

Go up

History of document

Go up