|
|
what's it all about?
The applications that can be developed with these Personal APIs can provide a huge value to you - the developer - and to your application users.
Be innovative and combine the different APIs into your application to create a unique service.
In a nutshell, the Personal APIs is a suite of the following APIs:
|
Authentication API
The Authentication API has two different purposes:
Firstly, it enables basic authentication and privacy functionality, so must be used before you use any of the other APIs.
Secondly, it simplifies access to your website for Orange users by allowing them to use their existing Orange account credentials.
 Give your visitors an improved online user experience.
Increase the amount of time visitors spend on your site.
Boost traffic to your web / WAP services.
find out more and play
|
|
Personal Calendar API
The Personal Calendar API gives your application real time access to Orange France customers' calendars, enabling you to view events and add new entries, with their permission.
The API provides a secure and controlled access to the user's calendar.
Give your visitors access to their calendar.
Increase web and TV audience figures.
find out more and play
|
|
Personal Contacts API
The Personal Contacts API gives your application real time access to Orange France customers' contacts, enabling you to view their address book and add new entries, with their permission.
The API provides a secure and controlled access to the user's contacts.
Give your visitors an easy way to add an entry to their contacts.
Decrease the amount of time spent on entering details into a form.
find out more and play
|
|
Personal Content API
The Personal Content API gives your application real time access to Orange France customers' “Mes données” service, enabling you to add large files from your site to their virtual data storage application, with their permission.
The API provides a secure and controlled access to the “Mes données” service of the user (for more information about the service “Mes données”, go to http://mesdonnees.orange.fr)
Give your visitors an easy way to add new digital content to their service “Mes données”.
Increase your presence into Orange France customers’ universe by storing photos, videos, musics and any other kind of file coming from your site.
find out more and play
|
|
Personal Favourites API
The Personal Favourites API gives your application real time access to Orange France customers' "Mes favoris", enabling you to add new entries redirecting to your website, with their permission.
The API provides a secure and controlled access to the "Mes favoris" service of the user (for more information about the service "Mes favoris", go to http://favoris.orange.fr/)
Give your visitors an easy way to add new entries to their favorites.
Increase your presence into Orange France customers' universe by adding favorites redirecting to your website.
find out more and play
|
|
Personal Messages API
The Personal Messages API gives your application real time access to Orange France customers' message box, enabling them to be alerted of their emails at any time.
And soon they'll be able to check their MMS and much more...
The API provides a secure and controlled access to the user's information about their messages.
Give your visitors an overview of last unread emails they have received.
Notify users of total number of unread emails and web SMS they have received.
Inform users of the total number of emails they have received.
find out more and play
|
|
Personal Photos API
The Personal Photos API gives your application real time access to Orange France customers' photo albums, enabling you to view photos and add new photos, with their permission.
The API provides a secure and controlled access to the user's Orange photo album.
Retrieve album and photo information about the user's Orange photo account, as well as image links to photos from the albums.
Import photos into existing or new Orange photo albums.
find out more and play
|
|
Personal Profile API
The Personal Profile API gives your application real time access to Orange France customers' profile information, enabling you to retrieve data such as name, email, address, phone number, etc..., with their permission.
The API provides a secure and controlled access to the user's profile.
Retrieve Orange France customers' profile information.
find out more and play
|
|
Personal RichProfile API
The Personal RichProfile API gives you a secure and controlled access to new customer’s profile information, on top of Personal Profile API information.
The API enables your application to retrieve about thirty attributes, including the customer’s photo and interests.
Retrieve Orange France customers' profile information.
find out more and play
|
(back to top)
two things to do before you get started
There are just two simple steps you need to follow before getting started...
 |
You need to be an Orange Partner Member in order to use the Personal APIs and access the administrator web interface.
If not already, become an Orange Partner member now
|
 |
Once signed into the Orange Partner site, access the administrator web interface and subscribe to the APIs. |
(back to top)
|
all about the API Manager
The API Manager allows you to control and configure all aspects of your Personal APIs alpha subscriptions.
Specifically you'll be able to:
gain immediate approval to use the APIs
request subscription to any or all of the APIs
gain approval for your subscription
and then receive your access key, endpoint URLs, sample codes and advanced technical documentation
The steps below describe important aspects of the interface:
The first time you log on to the API Manager, we will ask you to fill in a form to provide us with information that includes:
your website URL
your website name
your website logo |
|
This information will help us validate your subscription.
The website information you provide will be displayed to the users to enable them to set their privacy settings, and will determine if the users will allow you - the developer - to access their personal information via the Personal APIs.
You will then have access to a screen, allowing you to request a subscription to any of the APIs.
Remember, you MUST subscribe to the Authentication API first.
Once your subscription has been validated, you will receive an email and a ZIP file file containing the following:
Your access key (SERVICE_ID and SERVICE PWD)
The API endpoint URL
Sample codes
Instructions on how to use it all.
(back to top)
how your service interacts with the APIs
As the APIs provide very sensitive and personal information about our customers, we need to ensure that it is not used without the customer's consent.
In order to access the Personal APIs suite, your online service has to gain the user's authentication and consent to use their personal information.
The diagram below shows a simplified illustration of the general interactions between the different entities:
The interactions require the use of HTTP Redirect. Please refer to the W3C protocol page if you are not familiar with these mechanisms.
The process for accessing a Personal API is as follows:
| step 1 |
The service requests the user's authentication by Orange. The service re-directs the user to the authentication URL. |
| step 2 |
The service receives the response containing the user token that will be used to identify the user in the Personal API request.
This user token is temporary and should be renewed in the same manner when expired.
Please refer to the Authentication API section for further details.
|
| step 3 |
The service requests the Personal API using the user token. |
| step 4 |
If the user has not already granted access to its personal data, the call will raise a privacy error where...
the service may invite the user to give their consent by re-directing to the user privacy URL and
the user will be asked to give a temporary or a permanent consent and be re-directed to your service. |
| step 5 |
After the privacy interaction with the user, the service can call the Personal API again. |
| step 6 |
If the user has granted access, the service receives the response from the Personal API. |
Note that for security reasons, your service needs to support Secure HTTP (HTTPS) to use the Personal APIs.
(back to top)
more information about privacy concepts
When personal information about an Orange France customer is requested through a Personal API, a Privacy Exception can occur (see general error codes section below) if the customer has not given their consent yet.
The Privacy Exception message contains a URL to a privacy page where you can re-direct the user to obtain their consent.
During their interaction with the privacy page, the user is given 3 choices:
To grant access to a particular set of data for your service once.
To grant access to a particular set of data for your service permanently (until they change their mind).
To deny access to a particular set of data for you service.
After this interaction, the user is re-directed to a specific page on your website where you can call the Personal API again.
Depending on the user's previous choice, you may get the user's data or not.
The diagram below shows an overview of the general user experience:
find out more about the Personal APIs privacy management process
(back to top)
start your development
To further clarify how the Personal APIs will interact with your service, we've created some sequence diagrams to show the different message interactions for two major scenarios.
main scenario
privacy scenario
main scenario
This is when the user has already given the consent to your service, but is not authenticated by Orange.
privacy exception scenario
This is when the user has not already given the consent, in which case you have to re-direct the user to the privacy page.
Please note that the user has to be authenticated by Orange as in the main scenario.
(back to top)
Personal APIs general error codes
When using the Personal API suite, you could get a return error code, indicating for example that you have to interact either with the Authentication API or to redirect to the privacy URL before your service calls the Personal APIs suite.
error response examples
The response for error code "-1" is in the following format:
|
<?xml version="1.0" encoding="UTF-8"?>
<error>
<code>-1</code>
<detail>InvalidTokenException</detail>
</error>
|
Error codes "-1" to "-10" follow the same format, except error "-3", which format is described hereafter:
|
<?xml version="1.0" encoding="UTF-8"?>
<error>
<code>-3</code>
<detail>PrivacyAccessDeniedException</detail>
<url>http://mdsp.orange.fr/privacy/interaction.do?
family=photos&serviceId=myDemoSP&attributes=,see</url>
</error>
|
The <url> parameter contains the URL of the privacy page that needs to be used to invite the user to give their consent for accessing the data required by the
Personal API.
To invite the user to give their consent, your service needs to re-direct the user to the <url> parameter concatenated with your return URL.
For example, if your return URL is "http://myservice.com/displaypage.php" - you need to re-direct the user to the following URL:
|
http://mdsp.orange.fr/privacy/interaction.do?family=photos&serviceId=myDemoSP-papi&attributes=,see&urlRetour= http%3A%2F%2Fmyservice.com%2Fdisplaypage.php
|
After this interaction, the user is re-directed to your return URL where you can call the Personal API again.
(back to top)
|
