The Form ID API gives you information for Orange customers authenticating on your service through the Orange Authentication API. It can typically be used to enhance your sign-up process time. Using qualified Orange information, you'll be able to automatically fill forms during sign-up process on your web site. You will need the end-user's consent in order to access his information. A dedicated UI is provided with the Orange Authentication API.
Before starting
Our Form ID API requires a 3-legged authentication with our OpenID Connect platform. Please follow the method described here, with form_filling scope, in order to get an access token that will be granted to retrieve end-user's claims.
Retrieve Orange customer's information
You need a valid access token to invoke the Form ID API. This access token must be provided in the HTTP Authorization header:
curl -X GET \
-H "Authorization: {authorization_header}" \
https://api.orange.com/formfilling/fr/v1/userinfo
As an example:
curl -X GET -H "Authorization: Bearer OFR-948ef...d5de1f4"
"https://api.orange.com/formfilling/fr/v1/userinfo"
a/ If the transaction succeed
In the context of the Form ID API, the form_filling scope gives permissions to the following claims only:
| Claim | Type | Description | |
|---|---|---|---|
sub | string | Subject - Issuer identifier for the end-user. | |
updated_at | number | Time the end-user's information was last updated. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. | |
name | string | End-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the end-user's locale and preferences. | |
given_name | string | Given name(s) or first name(s) of the end-user. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters. | |
family_name | string | Surname(s) or last name(s) of the end-user. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters. | |
birthdate | string | End-user's birthday, represented as an ISO 8601:2004 YYYY-MM-DD format. The year MAY be 0000, indicating that it is omitted. To represent only the year, YYYY format is allowed. | |
gender | string | End-user's gender. Values defined by this specification are female and male. Other values MAY be used when neither of the defined values are applicable. | |
address | JSON object | End-user's preferred postal address. See Address structure below. | |
email | string | End-user's preferred e-mail address. Its value MUST conform to the RFC 5322 addr-spec syntax. | |
subscriber_msisdn | string | User's mobile number linked to his Orange subscription [E.164]. | |
phone_number | string | End-user's preferred telephone number (E.164). | |
locale | string | The native language of the user [BCP47]. E.g: fr-FR |
The Address JSON object represents a physical mailing address. It is bound of the following attributes:
|Attribute|Type|Description| | |:-:|:-:|:-| | |formatted|string|Full mailing address, formatted for display. MAY contain multiple lines, separated by newline characters (\n or \r\n). | | |street_address|string|MAY contain house number, street name, PO Box number. If using multiple lines, the lines are separated by newline characters. | | |locality|string|City, Town. | | |region|string|State, Province, County. | | |postal_code|string|Post Code, ZIP code. | | |country|string|Country name. | |
On success, the UserInfo request returns a 200 OK HTTP status code with JSON data containing requested claims about the end-user.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 580
Cache-Control: no-store
Pragma: no-cache
{
"sub": "USFPGN-200-i6jmJ/GFYJhkINg...Y/X7yA="
"updated_at" : "1457075253",
"name": "Christine Dumontel",
"given_name": "Christine",
"family_name" : "Dumontel",
"birthdate" : "1978-11-25",
"gender" : "female",
"address" : {
"formatted" : "11 rue des Lilas\r\n75018 Paris",
"street_address" : "11 rue des Lilas",
"locality" : "Paris",
"postal_code" : "75018",
"country" : "France"
},
"email" : "christ178.dumontel@orange.fr",
"subscriber_msisdn" : "+33(0)601020304",
"phone_nuber" : "+33(0)144332211",
"locale" : "fr-FR"
}
b/ If the transaction failed
In case of error, the UserInfo endpoint returns an error response (JSON format) with the following information:
- error (required): single ASCII error code
- error_description (optional): Human-readable ASCII text providing additional information, used to assist the developer in understanding the error that occurred.
If the access_token is expired, revoked or invalid, a 401 Unauthorized HTTP status code is returned with the invalid_token error code. In that case, you'll have to renew the access token.
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
{
error="invalid_token",
error_description="The access token provided is expired, revoked, malformed, or invalid for other reasons"
}
If the end-user revoked its consent using its OpenID Connect dashboard, a 403 Forbidden HTTP status code is returned with the insufficient_scope error code. In that case, you'll have to redo the Authorization request in order to get back an new authorization code, then request a new access token.
HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
{
error="insufficient_scope",
error_description="no consented scopes"
}
Please note that common errors which format is not fully compliant with OpenID Connect standard may also be returned.
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
{
"code": 60,
"message": "Resource not found",
"description": "The requested URI does not exist."
}
See API Reference section for the exhaustive list of error codes.
We will always be there to support you if needed.