before getting started
Before getting started, please read the information below, and follow any instructions.
You'll then be ready to move onto the 'getting started' section.
two things to do before you get started
all about the API Manager
two things to do before you get started
To start playing with this API, please make sure you have read and understood the
Personal APIs (alpha) section
 |
You need to be an Orange Partner Member in order to use the Personal Contacts API and access the administrator web interface.
If not already, become an Orange Partner member now
|
 |
Access the API Manager |
And then, within the API Manager, you'll be able to subscribe to the Personal Contacts API.
|
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 administrator web interface, 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 containing the following:
Your access key (SERVICE_ID and SERVICE PWD)
The API endpoint URL
Sample codes
Instructions on how to use it all.
access the API Manager
getting started
Now that you've read the 'before getting started' section, and become familiar with administrator web interface, you're ready to learn about...
how to authenticate the user
adding a "Hello World" event
Personal Contacts API methods in detail
Personal Contacts API error codes
Also, make sure your familiar with the Personal APIs privacy management process.
The process protects Orange users by preventing third parties from accessing their personal data without their permission. Find out more
how to authenticate the user
Firstly, users need to be authenticated before access to their contacts is granted.
The authentication is done through the Authentication API which will return a user token.
You will then include the user token in all Personal Contacts API calls.
Below is an example of how the call is made:
|
Format:
[My ContactsV1URL]?action=[action name]&token=[user token]¶m=[value]...
Example:
[My ContactsV1URL]?action=getcontact&token=Hjlkzjlfkzef23423kjlkjr¶m=value...
|
If you want to see whether your code has worked, we can provide you with an Orange customer test account, so you can see the results as if you were an Orange customer. Once your subscription is validated, we'll show you how you can get one.
adding a "Hello World" contact
Adding a "Hello World" contact to the contacts of an Orange customer is easy.
Firstly, retrieve a user token using the Authentication API. This user token will be used as the "token" parameter in the Personal Contacts API call.
For more information, see how to authenticate the user section.
You will then be able to call the following request (adding a "Hello World" contact):
|
[My ContactsV1URL]?action=addcontact&token=[user token]&lastname=World&firstname=World&
nickname=HelloWorld&company=Orange&function=JobTitle&department=World&
emailperso=hello.world@helloworld.com |
The above code will add the contact to the user's Orange Contacts. Easy.
Personal Contacts API methods in detail
Personal Contacts API provides four methods:
findcontactlist
getcontact
addcontact
adddevice
getpicture
addpicture
findcontactlist
Find contacts matching a search criteria.
To call the API, create the following URL format in your web application and invoke it through HTTP GET:
|
Format:
[PersonalContactsV1URL]?action=findcontactlist&
search=[search string]&token=[user token]
Example:
[PersonalContactsV1URL]?action=findcontactlist&
search=Orange&token=Hjlkzjlfkzef23423kjlkjr |
input parameters
| Name |
Description |
Mandatory |
Type |
| search |
The first characters of the first name or last name of contacts to find.
Wild cards (*) are forbidden and complex strings must be put between " " and URLEncoded,
for example: %22complex+string%22, Orange.
|
Yes |
String |
| token |
user token that is retrieved using the Authentication API. |
Yes |
String |
sample response
|
<?xml version="1.0" encoding="UTF-8" ?>
<xpage version="1.0">
<command-list>
<command request="g10" action="ctcfindcontactlist">
<data-list total-data="2" nbpage="1" page="1" nbentries="2">
<data view="shallow" id="1" type="contact">
<firstname>Orange</firstname>
<lastname>World</lastname>
</data>
<data view="shallow" id="2" type="contact">
<firstname>Orange</firstname>
<lastname>Partner</lastname>
</data>
</data-list>
<result>0</result>
</command>
</xpage> |
description of the response nodes
| Name |
Description |
| data-list |
List of the contacts matching the query. |
| data |
Contact entry, containing his/her first name and last name. |
| result |
Result code of the response. 0 means that the operation was successful. |
(back to API methods in detail)
getcontact
Get details of a contact.
To call the API, create the following URL format in your web application and invoke it through HTTP GET:
|
Format:
[PersonalContactsV1URL]?action=getcontact&
cid=[contact id]&token=[user token]
Example:
[PersonalContactsV1URL]?action=getcontact&
cid=C1&token=Hjlkzjlfkzef23423kjlkjr |
input parameters
| Name |
Description |
Mandatory |
Type |
| cid |
The unique identifier of the contact details to be retrieved.
The value is the "id" value within the <data view> parameter in
the findcontactlist response.
|
Yes |
String |
| token |
user token that is retrieved using the Authentication API |
Yes |
String |
sample response
|
<?xml version="1.0" encoding="UTF-8" ?>
<xpage version="1.0">
<command-list>
<command request="g10" action="ctcgetcontact">
<data-list>
<data view="deep" id="1" type="contact">
<firstname>Robert</firstname>
<lastname>Smith</lastname>
<civility>0</civility>
<maritalstatus>0</maritalstatus>
<birthday>1951-01-01</birthday>
<company>Custland Ltd</company>
<device-list>
<device display="true" id="1400761728" info-type="pro" order="1" subtype="internet" type="email">rob516.smith@custlandcy.com</device>
<device display="true" id="1295666158" info-type="perso" order="1" subtype="voice" type="phone">0123456789</device>
<device display="false" id="1400732085" info-type="perso" order="1" subtype="web" type="url">www.robsmith516.com</device> </device-list>
<address-list>
<address info-type="home">
<streetline1>24, Fascination Street</streetline1>
<streetline2>Appt 34</streetline2>
<zip-code>766546</zip-code>
<city>London</city>
<state>England</state>
</address>
</address-list> </data>
</data-list>
</command>
</command-list>
</xpage><?xml version="1.0" encoding="UTF-8" ?>
<xpage version="1.0">
<command-list>
<command request="g10" action="ctcgetcontact">
<data-list>
<data view="deep" id="1" type="contact">
<firstname>Robert</firstname>
<lastname>Smith</lastname>
<civility>0</civility>
<maritalstatus>0</maritalstatus>
<birthday>1951-01-01</birthday>
<company>Custland Ltd</company>
<device-list>
<device display="true" id="1400761728" info-type="pro" order="1" subtype="internet" type="email">rob516.smith@custlandcy.com</device>
<device display="true" id="1295666158" info-type="perso" order="1" subtype="voice" type="phone">0123456789</device>
<device display="false" id="1400732085" info-type="perso" order="1" subtype="web" type="url">www.robsmith516.com</device> </device-list>
<address-list>
<address info-type="home">
<streetline1>24, Fascination Street</streetline1>
<streetline2>Appt 34</streetline2>
<zip-code>766546</zip-code>
<city>London</city>
<state>England</state>
</address>
</address-list> </data>
</data-list>
</command>
</command-list>
</xpage> |
description of some of the response nodes
| Name |
Description |
| data |
Contact entry, containing his/her personal information. |
| civility |
0=unknown, 1=Mr, 2=Mrs, 3=Miss. |
| device-list |
List of the devices associated to the contact. |
| device |
Communication device, defined by its type and subtype:
type - associate subtypes.
email - internet
phone - voice, cell, fax, video
url - web |
| address-list |
List of the addresses associated to the contact. |
(back to API methods in detail)
addcontact
Add a contact to the user's contacts.
To call the API, create the following URL format in your web application and invoke it through HTTP GET:
|
Format:
[PersonalContactsV1URL]?action=addcontact&lastname=[last name]&
firstname=[first name]&nickname=[nickname]&company=[company]&
function=[function]&department=[department]&
emailperso=[emailperso]&token=[user token]
Example:
[PersonalContactsV1URL]?action=addcontact&lastname=World&
firstname=Hello&nickname=HelloWorld&company=Orange&
function=function&department=department&
emailperso=hello.world@helloworld.com&token=Hjlkzjlfkzef23423kjlkjr |
input parameters
| Name |
Description |
Mandatory |
Type |
| lastname |
The last name of the contact. |
At least one of these four fields must be present in the request |
String |
| firstname |
The first name of the contact. |
String |
| nickname |
The nickname of the contact. |
String |
| company |
The company of the contact. |
String |
| function |
The function of the contact. |
No |
String |
| department |
The department of the contact. |
No |
String |
| emailperso |
The email of the contact. |
No |
String |
| birthday |
The date of birth of the contact. |
No |
ISO8601 |
| civility |
The civility of the contact:
- 0 : unknown
- 1 : Mr
- 2 : Mrs
- 3 : Miss |
No |
Integer |
| token |
user token that is retrieved using the Authentication API |
Yes |
String |
sample response
|
<?xml version="1.0" encoding="UTF-8" ?>
<xpage version="1.0">
<command-list>
<command request="g10" action="ctcupdatecontact">
<result>0</result>
<id>c6</id>
</command>
</command-list>
</xpage> |
Where <result> contains the return code of the operation. 0 means that the operation was successful.
(back to API methods in detail)
adddevice
Associate a device defined by its type and subtype to an existing contact.
The available device types along along with ther associated subtypes:
type - associate subtypes.
email - internet
phone - voice, mobile, fax, video
url - web
To call the API, create the following URL format in your web application and invoke it through HTTP GET:
|
Format:
[PersonalContactsV1URL]?action=adddevice&cid=[contact id]&type=[device type]&
subtype=[device subtype]&order=[order]&value=[value]&token=[user token]
Example:
[PersonalContactsV1URL]?action=adddevice&cid=c6&type=phone&
subtype=voice&order=5&value=0123456789&token=Hjlkzjlfkzef23423kjlkjr |
input parameters
| Name |
Description |
Mandatory |
Type |
| cid |
The unique identifier of the contact details to be retrieved.
The value is the "id" value within the <data view> parameter in
the findcontactlist
|
Yes |
String |
| type |
Device type (email, phone, url). |
Yes |
String |
| subtype |
Device subtype :
- internet (email)
- voice, mobile, fax, video (phone)
- web (url) |
Yes |
String |
| order |
Display order |
Yes |
String |
| value |
Device identifier (phone number, email address, etc) |
Yes |
String |
| token |
user token that is retrieved using the Authentication API |
Yes |
String |
sample response
|
<?xml version="1.0" encoding="UTF-8" ?>
<xpage version="1.0">
<command-list>
<command action="cdvupdatedevice" request="g10">
<result>0</result>
</command>
</command-list>
</xpage> |
Where <result> contains the return code of the operation. 0 means that the operation was successful.
(back to API methods in detail)
getpicture
Get the picture of a contact.
To call the API, create the following URL format in your web application and invoke it through HTTP GET:
Format:
[PersonalContactsV1URL]?action=getpicture&
cid=[contact id]&token=[user token]
Example:
[PersonalContactsV1URL]?action=getpicture&
cid=C1&token=Hjlkzjlfkzef23423kjlkjr |
input parameters
| Name |
Description |
Mandatory |
Type |
| cid |
The unique identifier of the contact.
The value is the "id" value within the <data view> parameter in
the findcontactlist response.
|
Yes |
String |
| token |
user token that is retrieved using the Authentication API |
Yes |
String |
sample response
<?xml version="1.0" encoding="UTF-8"?> <xpage version="1.0">
<command-list> <command action="ctcgetmedialist" request="aaa">
<data-list> <filename content="/9j/4AAQSkZJRgABAQAAAQABAA
D/2wBDAAkGBwgHBgkIBwgKCgkLDRYPDQwMDRsUFRAWIB0iIiAd
Hx8kKDQsJCYxJx8fLT0tMTU3Ojo6Iys/RD84QzQ5Ojf/2wBDAQoKCg
0MDRoPDxo3JR8lNzc3Nzc3 Nzc3Nzc3Nzc3Nzc3Nzc3Nzc3Nzc3Nz
c3Nzc3Nzc3Nzc3Nzc3Nzc3Nzc3Nzf/wAARCACCAIIDASIAAhEBAx
EB/8QAGwABAAIDAQEAAAAAAAAAAAAAAAEFAwQGAgf/xAB
AEAABAwMBBQQHAwkJAAAAAAAB AAIDBAURIRITMUFRBmFxg
RQVIiMyUpFiocEWM0JDcoKSscIHJDREc4Oi8PH/xAAUAQEAAAAA
AAAA AAAAAAAAAAAA/8QAFBEBAAAAAAAAAAAAAAAAAA
AAAP/aAAwDAQACEQMRAD8A+4IiICIiAtavuFHb YN/X1UNPFnG1K
8NBPQZ4nuWhdLtM2sFstMTZq8t2pHvBMVMw8HSY1JOuGjU4OoG
SvFs7PwU1T6fV yy1lxcMOqqjBc0fKwDRje5vnk6kPDe0TqpwFptVb
VtP66Rm4jHm/Dj5NKh1d2jeMNtttpvtTVr3/ AHNjA+9XmwM5I1681Ib4
DwQURqu0TD+ZtEo6iaRn9JXl11v0Q2n2eilA4iC4na8g6MD7wugx3l
MfaKChHahkf+PtF2pAP0jTb5v1iL1aW65UNzh31vqoaiMHDjG7Oyeh
HEHuOqzmJh1LGE9cYKqrl2fo ax/pGw6Cra3DamFxZI399uHY7jkdy
C5Rc9brrU2+sjtd9ftOkdsUtcQAJzyY8DRsnho7lg+yOhQE REBERA
REQFo3qv8AVlsmqmx72VoDYYh+skcdljfNxA81vKhuDjX9qKGiAz
DQxmsl/bdlkQ+m9Pk1 Bu2S3erqMMkk3tTI4y1ExGDLKfid+AHIADkrF
QFKAiIgKFKICIiCuvVuiuVvmppcgSNxtN0c08QQ eRBAI7wFh7N3G
Wuonw1pb6wpH7mqDdAXAZDwOjgQ4dM45FWzuHhquZnPq3tvR
SjSG5076V+OBkjz JH/xMoQdOiIgIiICIiAuc7Iv9PNxu/FtbVuMLscYme
7YR3ENLv3ludr5pafsxdJYHmN7aZ+JBxYM YLvIZPksdJV0dniorfN
u6aMtEUBcQG5A0Znk7A0B48uaC7RQDnClAREQEWrc7hBbaR1RU
FxGQ1jG DL5Hk4a1o5knQBVdRdLhHsvqfVtsjdnYbW1G1I/ybho8nO
QXyLnIu0E0GZqs0dVQhzWyVVDJn0ck ge8YTkN1ztAnA1IAGV0aC
MLme3TA22Q1gJbJR1UFQx3Qtfr5EZB7iunXNf2gg/krcS0ElkBdp3An
8EHSooGoyFKAilEEIiIMNZ6P6JN6Zu/Rt27e7zGzsY1znljOVxd2pJJux
lFC1lQblLsi3ZeWysf7Tow5+QWkRghxJ+biTg9DdsXKvhs7dYQBPW
/6YPsRn9twOerWOHML1d9iW5WylkaHNfK6QZ5OYA5p+qCOy1Bc
qC2bq8VjKmoMjnAsboxp4NzgbRHzYBP3q4ChnwhSgIiIKO/09bLcLZ
JRRNeWOkAe8ZbA 9zQBIRzw3eDHMkDTOVu2630tEC6FhfO/G8qJ
PallPHLnc/DgOQA0WW4tc6jlbFMYZdkmN7eLXcjj nry5rVsFQ6otsM8
md/I0GVpBG7f+kzB1GDka9EGr2mZSxsFRPC1/93nZNkfFBu3FzT1G
Q1Wdpjli tdHHUvc+ZkDGyOcclzg0ZJ81Q3Zwut4FtjO212IpMcBC0h8
xPc73cfiXdDjqUEFc524zNZ30reNT LFT/AMb2s/rK6MkAEnkuduoNxv
8AbLewZbA/02od8rWHDB4ueQfBh6IOjCIEQEUoghERByNuvNJZQ6i
uMNRHXyTPdNI6I+/eXEBzSfjy0NwG5wMNwMYFjXSslqrTW07y+MS
Euy0ghr24zrqNcceq373P BTWmqlqYBURiMgwFodvSdAzB0OSQPN
eKChMFppKSVwfJFAyN72n4i0AE/Uc0G/Hw8F6XlowfFekB ERBoSy
vivMEeSY54H6dHMII+oc76BYb7NHS02+nnqfacI46emcGvnefhY08cn
xAAyTgAkbNwoRWC FzZpIJ4X7cUsWMtOCCMEEEEHUH+YBWKktEU
NWKypmmrKsAtZNUEe7B4hjQA1ueZAyeZKDF2etAtl M50oYayfDpnM
yWjjhjc67LcnHUkuOrirbKLy8kDIQalzrYaGkkqahxEUQycDJJ5ADmScA
DmSFrWC hmgZPW1zQ2urHB8rAciJoGGRg/ZGc9XOcRoQsMUXrW9O
fIM0dteGxsP6yoIBLj3NDgB9ouPFoKvE BERAREQEREGKpp4aqnkgqYm
SwyN2XseMhw6ELlLdNVOuVMLHR3NtuMhEktVOx1O6MEglrXPMjeHs
4AB0yMajsFR22AUN9rqWlc4Uhijn3JOWxyPdJtbPQHZzs8M6jGSgu1K
hSgIoQ4AJIQCRkaoOCxvP BgGpWQDCCV4k4L11XmTgf+8kFd2eINFO
4cTW1OfKZ4/BWipezx3VVd6Jx9qOsMrR1ZIA7P8AFvB+ 6VdICIiAiIgIiI
Co66WS1Xl9fLDJJQ1MLI5ZImF5gewuIc5oydkh+MgaFuuhyLxEFQe01l
DQRcqZ +RkBjw4/QZKxflXaTwmnI6tpJj/QrzzRBz7e11rlqhSUzp56ojIp
2wPa8jr7YGnet+lnrKlofPSu pejXSAkDv049w+qx3yKMzW2d4G1FVta
HdA9rmkeeR546KyIzH4jigxxghzy47TjgAnp0WdYYyXOJ PM6Dw/8AV
l8UBQdAfHKlOeCOIQUddm33ujrhpFMRRz920fduPg/2f91Xq0LnRMuND
PSyuLWysLC9 vFp+Yd4OCO9oSx1kldbIpahoZUtzFUNHBsrCWvx3bQO
O7CDfREQEREBERAREQEREFff4XT2arbF+ dZHvYj0kZ7TD/E0LZilbPTx
Ss+GRoc3wOv8AJZnAOaWngRgrn6a4SWW300F5pnQRwRNiNW14fC
SG 4GTo5ue9uM4GckZC9A2dSeC94zhVUNXc6tu9gt0cUDj7HpczmSEd
SwMOznoTnqAdFlLrweEdAzv3 j3Y8tkILHooPEFVxhvDv87Qs8KR5x57
z8FBttVKMT3esIPFsTY4x5HZ2h9UGW419PbojLVPwHECN jRtPkd8rGjV
zjjgFFkgnhodqrYGVE8j5pGB2dgucSG5HHAwM88KaO00NHMZ4YAagg
tM8rjJIR023 Eux3ZW8gIiICIiAiIgIiIClEQQodwREEhERAREQEREBERBKIiD//
2Q==" display="false" id="1429530340" info-type="perso" order="1"
subtype="picture" type="media"/> <typeImage>gif</typeImage>
</data-list><result>0</result> </command> </command-list>
<parameter-list/> </xpage> |
description of some of the response nodes
| Name |
Description |
| data-list |
Entry of the contacts list. |
| filename |
The file of the picture wich is encoded in base 64 int the content attribute. |
| typeImage |
The type of the picture : gif, jpeg ou bmp. |
(back to API methods in detail)
addpicture
Add a picture of a contact.
The following images formats are accepted: JPEG, GIF, BMP
To call the API, create the following multi-part message in your web application and post it to [PersonalContactsV1URL] :
Exmple:
POST [PersonalContactsV1URL] HTTP/1.1
Content-Type: multipart/form-data;boundary=---------------------------41184676334
Content-Length: 29277
-----------------------------41184676334
Content-Disposition: form-data; name="action"
add picture
-----------------------------41184676334
Content-Disposition: form-data; name="cid"
C1
-----------------------------41184676334
Content-Disposition: form-data; name="token"
Hjlkzjlfkzef23423kjlkjr
-----------------------------41184676334
Content-Disposition: form-data; name="file"; filename="picture.jpg"
Content-Type: image/jpeg
[binary content] |
input parameters
| Name |
Description |
Mandatory |
Type |
| cid |
The unique identifier of the contact.
The value is the "id" value within the <data view> parameter in
the findcontactlist response. |
Yes |
String |
| token |
user token that is retrieved using the Authentication API. |
Yes |
String |
| file |
File to upload. |
Yes |
String |
sample response
<?xml version="1.0" encoding="UTF-8" ?>
<xpage version="1.0">
<command-list>
<command action="ctcaddmedia" request="g10">
<result>0</result>
</command>
</command-list>
</xpage> |
Where <result> contains the return code of the operation. 0 means that the operation was successful.
(back to API methods in detail)
Personal Contacts API error codes
When an error occurs, the response contains an error code ('type' parameter), an internal subtype and the message:
|
<command request="" action="action">
<result>-yyy</result>
<error subtype="xxx" type="yyy">message</error>
</command> |
Here is a table which describes the most significant errors:
| Error Code |
Status |
Message |
| 1 |
unkown action |
'mandatory parameter' is missing. |
| 2 |
missing parameter |
'parameter' is invalid. |
| 4 |
invalid parameter |
The command 'action' is unknown. |
| 5 |
invalid user ID |
'end-userid' is incorrect (database is corrupted). |
| 100 |
data not found |
Service AddressBook not provisioned for the user. |
(back to top)
