[[:guide_du_developpeur_service|Français]] | [[:en:guide_du_developpeur_service|English]]
----
====== Developer Guide – ID360 Service ======

=== 🎯 The ID360 solution allows you to: ===
  * ✅ Manage user **identification** and **authentication** for your business service.
  * 🗂️ (Optional) **Collect**, **store**, and **verify the authenticity** of additional documents.
  * 🎨 Customize a **user interface** according to your needs.

----

=== 🔗 Swagger Access ===
  *  **[[https://preprod.id360docaposte.com/static/swagger.html|Swagger Preproduction]]**
  *  **[[https://id360docaposte.com/static/swagger.html|Swagger Production]]**

----

=== 🔧 Key API Operations ===

Here are the main steps to implement in your integration:

  - **API Login**: This call provides a token valid for 15 minutes, which grants access to the various API methods.
  - **Creating a user enrollment**: When creating a user enrollment, you will receive an enrollment ID and an API key (api_key), which will be essential for the rest of the process.
  - **Route selection**: The api_key obtained in the previous step allows you to retrieve the identifier of the “route” to be executed. In your use case, there will be only one route available – the customizable online process by Docaposte.
  - **Acceptance of Terms & Conditions**: This method allows you to update the fields `accept_cgu` and `accept_biometry` within the enrollment.
  - **Data comparison (optional)**: It is also possible to compare expected data with information extracted from the identity document.
  - **Identity document upload**: Upload of the ID document is performed at this step.
  - **Selfie upload (optional)**: A selfie image can also be uploaded to enable biometric facial comparison with the ID document.
  - **Finalizing the enrollment**: Finalizes the user enrollment.
  - **Retrieving the report**: You can retrieve the user enrollment report using the enrollment ID obtained in step two. The report includes the status of the enrollment, technical information, and details of the verification steps.
  - **Retrieving the idClaim (optional)**: Only in the case of advanced electronic signature, returns an ASIC-E.

----

📘 **To continue reading this guide, you must have already created at least one route and one application.**

If you haven't done so yet, we recommend starting with the first section of this guide: **Getting Started with ID360**

====== 1. API Login ======

==== 1.1 API Login: Authentication ====

[[https://preprod.id360docaposte.com/static/swagger.html#/user/login|See method in Swagger]]

----


=== 🔧 Requête CURL – Production ===
<code javascript>
curl -X POST "https://id360docaposte.com/api/1.0.0/user/login/" \
  -H "accept: application/json" \
  -d '{ "username": "string", "password": "string", "token": "string" }'
</code>

=== 🔧 Requête CURL – Préproduction ===
<code javascript>
curl -X POST "https://preprod.id360docaposte.com/api/1.0.0/user/login/" \
  -H "accept: application/json" \
  -d '{ "username": "string", "password": "string", "token": "string" }'
</code>
----

=== 📥 Required Parameters ===

^ Parameter  ^ Required ^ Details ^
| ''username''  | Yes      | Login identifier |
| ''password''  | Yes      | Password |
| ''token''     | No (except for admin) | Unnecessary for `application` accounts. Required only for `admin` accounts with two-factor authentication |

----

=== 📤 Expected Result (example) ===

**HTTP Status**: `200 OK`

**Response Body**:
<code javascript>
{
  "token": "0123456789abcdef01234567"
}
</code>

----

=== 💬 Notes ===

  * This call **must be made by your server**, **never** from the user’s browser.
  * The **token is valid for 15 minutes**. This duration **resets on each API call** using the token.
  * If you use an expired token or no token, you’ll get a `401 Unauthorized` error.
  * As long as the token is valid, **do not call `/login/` again**.
  * Use the token in the header of future calls:''Authorization: Token 0123456789abcdef01234567''
  * The token is made up of 25 characters (fixed length).

----


==== 1.2 Headers for your API Requests ====

{{:headers.png|Headers example}}

Essential header for your API calls:

**`Authorization`** → must contain:
  * the prefix **`Token`**
  * a space
  * the **token value** from the login call

**Example**:
<code>
Authorization: Token 0123456789abcdef01234567
</code>

----

=== Testing via Swagger ===

To test calls in Swagger:
  - Click **"Try it out"** (top right)
  - Enter the token in this format: `Token 0123456789abcdef01234567`
  - Then click **"Authorize"**

You will then be authenticated to run API calls directly from Swagger.

----

==== ⚠️ 1.3 Token lifespan and refresh – MUST BE IMPLEMENTED ⚠️ ====

The **login token is valid for 15 minutes**, and its lifespan is **reset with every call using the token** (*except `logIn` itself*).

If you are not connected or the token is expired, you will receive a **401 Unauthorized** for any operation requiring authentication.

----

=== 🔁 Extending Token Validity ===

To extend token lifespan, you may call this method **every 13 minutes**:
**`/api/1.0.0/user/whoami`**

This method:
  * Requires **no parameters**
  * Requires an **Authorization header**:

<code>
Authorization: Token 0123456789abcdef01234567
</code>

----

=== ✅ Validity Check ===

  * If the method returns **200 OK**, your token is still valid.
  * Otherwise, generate a **new token** via the `logIn` method.

**ℹ️ Reminder: integrate this call automatically into your process to avoid repeatedly calling the logIn method, as this may be interpreted by ID360 as abnormal or aggressive behavior.**

====== 2. Creating a User Enrollment ======

[[https://preprod.id360docaposte.com/static/swagger.html#/process/process_enrollment_create|See the method in Swagger]]

----

=== 🔧 CURL Request – Production ===
<code javascript>
curl -X POST \
  "https://id360docaposte.com/api/1.0.0/process/{id}/enrollment" \
  -H "Authorization: Token 0123456789abcdef01234567"
</code>

----

=== 🔧 CURL Request – Preproduction ===
<code javascript>
curl -X POST \
  "https://preprod.id360docaposte.com/api/1.0.0/process/{id}/enrollment" \
  -H "Authorization: Token 0123456789abcdef01234567"
</code>

----

=== 🛠 URL Notes ===

Replace the ''{id}'' part with the **UUID of a process**.  
Process objects are configurable through the admin UI (their UUID is displayed there).

----

=== 📥 Expected Body ===

<code json>
{
  "browser_callback_url": "https://www.example.com/browser_callback_url",
  "client_reference": "any_string", 
  "callback_endpoints": [{
    "url": "https://www.example.com/callback_url1",
    "on": ["E","F","C"],
    "headers": [{"name": "string", "value": "string"}]
    },{
    "url": "https://www.example.com/callback_url2",
    "on": [],
    "headers": [{"name": "string", "value": "string"}]
  }],
  "callback_headers": {
    "header_name_1": "header_value_1",
    "header_name_2": "header_value_2"
  },
  "last_name": "Users last name",
  "first_name": "Users first name",
  "email": "Users email",
  "address_line_1": "Users address line 1",
  "address_line_2": "Users address line 2",
  "address_line_3": "Users address line 3",
  "zip_code": "Users zip code",
  "city": "Users city",
  "country": "Users country",
  "phone_number": "Users phone number",
  "group": "string"
}
</code>

----

=== 📝 Field Details ===

  * **''browser_callback_url''**: required – URL triggered by the user's browser at the end of the process (used for redirection only).
  * **''client_reference''**: optional – Allows you to associate an internal ID from your system. Useful for reconciliation in case of cancellation or failure.
  * **''callback_endpoints''**: required – A callback endpoint allows ID360 to automatically notify your system when an enrollment reaches a certain status (e.g., failure, cancellation, completion), via an HTTP POST request sent to the provided URL. Headers are optional and can be used for identification when receiving callbacks.
  * **''last_name, first_name, address_line_1/2/3, zip_code, city, country, phone_number, email''**: optional – User information provided for **informational purposes only** (no validation is performed).
  * **''group''**: optional – Enables consumption exports grouped by logical units.

> For more details on callback_endpoints, refer to [[https://wiki.id360docaposte.com/doku.php?id=guide_callbacks|this dedicated guide]].

----

=== 📤 Expected Response (example) ===

**HTTP Status**: ''200 OK''

<code json>
{
  "url": "https://www.id360docaposte.com/api/1.0.0/enrollment/{id}",
  "id": "{id}",
  "process": 1,
  "api_key": "0123456789abcdef0123456789abcde",
  "browser_callback_url": "yyy",
  "client_reference": "any_string",
  "status": "NEW",
  "reason": null,
  "creation_time": "2021-12-17T15:01:49.013906",
  "starting_time": null,
  "finished_time": null;
  "callback_endpoints": [{
            "url": "https://dev.webhook.id360docaposte.com/66b905f6-ac91-4a2c-8b1b-752d2393ac3b",
            "on": ["E","F","C"],
            "headers": [{"name": "string"}]
        },{
            "url": "https://dev.webhook.id360docaposte.com/66b905f6-ac91-4a2c-8b1b-752d2393ac3b",
            "on": [],
            "headers": [{"name": "string"}]
  }]
}
</code>

----

=== 💬 Notes ===

  * This call **must be made server-side**, never from the user's browser.
  * ⚠️ **It is essential to store the enrollment ''id'' and the ''api_key''** for the rest of the process.

====== 3. Route Selection ======

In some processes, two identification methods may be offered to the end user, such as:

  * Identification via La Poste’s Digital Identity;
  * Identification through Docaposte’s Customizable Online Process.

In our specific process, only the Docaposte Customizable Online Process has been selected, offering a single authentication channel.

This guide outlines the steps to retrieve the route identifier and select it within this process.

===== 3.1 Retrieving the Route Identifier =====

[[https://preprod.id360docaposte.com/static/swagger.html#/Enrollment%20Flow/flow_enrollment_info|See the method in Swagger]]

----

=== 🔧 CURL Request – Production ===

<code bash>
curl -X GET \
  "https://id360docaposte.com/api/1.0.0/enrollment/flow/enrollment_info/" \
  -H "accept: application/json" \
  -H "x-api-key: <your_api_key>"
</code>

=== 🔧 CURL Request – Preproduction ===

<code bash>
curl -X GET \
  "https://preprod.id360docaposte.com/api/1.0.0/enrollment/flow/enrollment_info/" \
  -H "accept: application/json" \
  -H "x-api-key: <your_api_key>"
</code>

----

=== 📝 Notes ===

  * **`x-api-key`**: replace the value with the **API key generated when creating the user enrollment**.
  * 📭 **No body** is expected in this request (the body must remain empty).

----

=== 📤 Expected Result (JSON excerpt) ===

<code json>
"routes": [
  {
    "id": 275128
  }
]
</code>

----

=== 💬 Comment ===

  * The **route identifier** to be used for the next step in the process is found in the `id` field.

===== 3.2 Route Selection =====

[[https://preprod.id360docaposte.com/static/swagger.html#/Enrollment%20Flow/flow_select_route|See the method in Swagger]]

----

=== 🔧 CURL Request – Production ===

<code bash>
curl -X POST \
  "https://id360docaposte.com/api/1.0.0/enrollment/flow/route/{route_id}/select/" \
  -H "accept: application/json" \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: text/plain"
</code>

=== 🔧 CURL Request – Preproduction ===

<code bash>
curl -X POST \
  "https://preprod.id360docaposte.com/api/1.0.0/enrollment/flow/route/{route_id}/select/" \
  -H "accept: application/json" \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: text/plain"
</code>

----

=== 📝 Notes ===

  * Replace **`<your_api_key>`** with the API key obtained when creating the user enrollment.
  * Replace **`{route_id}`** in the URL with the **route identifier** retrieved in the previous step.
  * 📭 No body is expected in the request.

----

=== 📤 Expected Result ===

**HTTP Status**: `204 No Content`

----

=== 💬 Comment ===

  * The selected route is now **linked to the API key** used in the request.

====== 4. Acceptance of Terms & Conditions ======

[[https://preprod.id360docaposte.com/static/swagger.html#/Enrollment%20Control/control_consent|See the method in Swagger]]

=== 🔧 CURL Request – Production ===

<code bash>
curl -X POST \
  "https://id360docaposte.com/api/1.0.0/enrollment/flow/consent/?accepted_cgu=true&accepted_biometry=true" \
  -H "accept: */*" \
  -H "x-api-key: <your_api_key>" \
  -d ''
</code>

=== 🔧 CURL Request – Preproduction ===

<code bash>
curl -X POST \
  "https://preprod.id360docaposte.com/api/1.0.0/enrollment/flow/consent/?accepted_cgu=true&accepted_biometry=true" \
  -H "accept: */*" \
  -H "x-api-key: <your_api_key>" \
  -d ''
</code>

----

=== 📤 Expected Result ===

**HTTP Status**: `204 No Content`

----

=== 💬 Notes ===

  * ✅ If you are only uploading an **identity or supporting document**, use `accepted_cgu=true` only.
  * ✅ If you are also uploading a **selfie**, make sure to add `accepted_biometry=true` in the URL.

====== 5. Data Comparison (optional) ======

In the process configuration, it is mandatory to select **at least one data field to compare**.  
To do so, go to the **''Information Entry''** block and choose the elements to compare.

[[https://preprod.id360docaposte.com/static/swagger.html#/Enrollment%20Control/control_data|See the method in Swagger]]

----

=== 🔧 CURL Request – Production ===
<code javascript>
curl -X POST \
  "https://id360docaposte.com/api/1.0.0/enrollment/{id}/control/data/{data_name}/?locked=true" \
  -H "accept: text/plain" \
  -H "Authorization: Token 0123456789abcdef01234567"
</code>

=== 🔧 CURL Request – Preproduction ===
<code javascript>
curl -X POST \
  "https://preprod.id360docaposte.com/api/1.0.0/enrollment/{id}/control/data/{data_name}/?locked=true" \
  -H "accept: text/plain" \
  -H "Authorization: Token 0123456789abcdef01234567"
</code>

----

=== 🛠 Technical Information ===

  * **''{id}''**: enrollment identifier, obtained during the creation of the user enrollment.
  * **''{data_name}''**: name of the data field to compare.
    - Examples:
      - ''name'' → last name
      - ''first_name'' → first name
      - ''birth_date'' → date of birth
  * To view the expected data fields, you can query:
    [[https://preprod.id360docaposte.com/api/1.0.0/enrollment/flow/enrollment_info]]

----

=== 📥 Parameters ===

^ Parameter ^ Value ^ Description ^
| ''locked'' | true | Locks the data once submitted (prevents further modification) |

----

=== 📤 Expected Body ===

The body must contain **only the value to be checked**, in raw format (plain text or simple value).

----

=== ✅ Expected Result ===

**HTTP Status**: ''204 No Content''  
This indicates that the comparison was successfully processed **and no response body is returned**.

====== 6. Identity Document Upload ======

[[https://preprod.id360docaposte.com/static/swagger.html#/Enrollment%20Control/control_document|See the method in Swagger]]

----

=== 🔧 CURL Request – Production ===

<code bash>
curl -X POST \
  "https://id360docaposte.com/api/1.0.0/enrollment/flow/document/id_document_image/?total_pages=2&uploaded_page=0" \
  -H "accept: */*" \
  -H "x-api-key: <your_api_key>" \
  --data-binary "@CNIRecto.PNG"
</code>

----

=== 🔧 CURL Request – Preproduction ===

<code bash>
curl -X POST \
  "https://preprod.id360docaposte.com/api/1.0.0/enrollment/flow/document/id_document_image/?total_pages=2&uploaded_page=0" \
  -H "accept: */*" \
  -H "x-api-key: <your_api_key>" \
  --data-binary "@CNIRecto.PNG"
</code>

----

=== 📝 Notes ===

  * **`x-api-key`**: replace with the API key generated when creating the user enrollment.
  * **`@CNIRecto.PNG`**: replace with the path to your file (e.g., image or PDF).
  * **`total_pages`**: indicates the **total number of pages** to be uploaded for the document (e.g., `2` for a front/back ID).
  * **`uploaded_page`**: index (starting at `0`) of the page currently being uploaded.
  * **Allowed formats**: jpg, jpeg, png, pdf, heic
  * **Maximum size** per document: 9.5 MB

----

=== 📤 Expected Result ===

**HTTP Status**: `204 No Content`

----

=== 💬 Notes ===

  * This step must be repeated for **each page of the document** to be uploaded.
  * A separate request must be made **for each page**, using the correct `uploaded_page` index and corresponding file.

====== 7. Selfie Upload (optional) ======

[[https://preprod.id360docaposte.com/static/swagger.html#/Enrollment%20Control/control_document|See the method in Swagger]]

----

=== 🔧 CURL Request – Production ===

<code bash>
curl -X POST \
  "https://id360docaposte.com/api/1.0.0/enrollment/flow/document/selfie_image_upload/?total_pages=1&uploaded_page=0" \
  -H "accept: */*" \
  -H "x-api-key: <your_api_key>" \
  --data-binary "@selfie.PNG"
</code>

----

=== 🔧 CURL Request – Preproduction ===

<code bash>
curl -X POST \
  "https://preprod.id360docaposte.com/api/1.0.0/enrollment/flow/document/selfie_image_upload/?total_pages=1&uploaded_page=0" \
  -H "accept: */*" \
  -H "x-api-key: <your_api_key>" \
  --data-binary "@selfie.PNG"
</code>

----

=== 📝 Notes ===

  * **`x-api-key`**: replace this value with the API key obtained during user enrollment creation.
  * **`@selfie.PNG`**: replace with the path to your image file (e.g., a photo taken by the user).
  * **`total_pages`**: must be `1` for a selfie.
  * **`uploaded_page=0`**: remains at `0` since there is only one page.
  * **Allowed formats**: jpg, jpeg, png, pdf, heic
  * **Maximum size** per document: 9.5 MB

----

=== 📤 Expected Result ===

**HTTP Status**: `204 No Content`

----

=== 💬 Notes ===

  * Uploading a selfie is **optional**, but required for processes involving biometric verification.
  * Make sure the parameter `accepted_biometry=true` was set during the acceptance of Terms & Conditions if a selfie is submitted.

====== 8. Finalizing the Enrollment – ⚠️ MANDATORY ======

[[https://preprod.id360docaposte.com/static/swagger.html#/Enrollment%20Flow/flow_finalize|See the method in Swagger]]

----

=== 🔧 CURL Request – Production ===

<code bash>
curl -X POST \
  "https://id360docaposte.com/api/1.0.0/enrollment/flow/finalize_enrollment" \
  -H "accept: application/json" \
  -H "x-api-key: <your_api_key>"
</code>

----

=== 🔧 CURL Request – Preproduction ===

<code bash>
curl -X POST \
  "https://preprod.id360docaposte.com/api/1.0.0/enrollment/flow/finalize_enrollment" \
  -H "accept: application/json" \
  -H "x-api-key: <your_api_key>"
</code>

----

=== 📝 Notes ===

  * Replace **`<your_api_key>`** with the API key obtained during the creation of the user enrollment.
  * 📭 No parameters are expected in the request body.

----

=== 📤 Expected Result ===

**HTTP Status**: `204 No Content`

----

=== 💬 Comment ===

  * This step is **mandatory** to ensure the enrollment is **processed immediately by the verification engines**.

====== 9. Retrieving the Report ======

===== 9.1 Retrieving the Report via API =====

[[https://preprod.id360docaposte.com/static/swagger.html#/enrollment/enrollment_report_retrieve|See the method in Swagger]]

----

=== 🔧 CURL Request – Production ===
<code javascript>
curl -X GET \
  "https://id360docaposte.com/api/1.0.0/enrollment/{id}/report" \
  -H "accept: application/json" \
  -H "Authorization: Token 0123456789abcdef01234567"
</code>

----

=== 🔧 CURL Request – Preproduction ===
<code javascript>
curl -X GET \
  "https://preprod.id360docaposte.com/api/1.0.0/enrollment/{id}/report" \
  -H "accept: application/json" \
  -H "Authorization: Token 0123456789abcdef01234567"
</code>

----

=== 🛠 Technical Information ===

  * **''{id}''**: user enrollment ID, obtained during its creation.
  * **Parameters**: no parameters are expected in this request.

----

=== ✅ Expected Result ===

**HTTP Status**: ''200 OK''  

**Response format**: JSON

----

=== 💬 Comments ===

  * This call must be made **from your server**, **never from the user's browser**.
  * The connection token is **valid for 15 minutes**, renewed with each API call using that token.
  * If the token is expired or missing, you will receive a **401 Unauthorized** error.
  * As long as your token is valid, **you must not reuse the ''login'' method**.
  * The token should be used in the*

===== 9.2 Retrieving the Report from the Admin Platform =====

The report is also accessible from the console, under the “User Enrollments” tab, for a duration of two months.  
The identifier corresponds to the enrollment ID generated at the end of step 2.  
By selecting “View Details,” you can view the identification report and download the evidence file in JSON format at the bottom of the page.

===== 9.3 Specificities =====

----

=== 📄 A Temporary Report ===

A temporary report is available **before** the final report is issued.  
This report can be retrieved using the **''allow_draft = true''** parameter, but **must not be used in production**.

⚠️ The report can only be retrieved **after receiving the ''callback_url''** notifying you of the enrollment's processing completion.

**Warning**:  
Calling a temporary report **may cause slowdowns or blockages** for your users.

----

=== 📄 A Report Issued Less Than 7 Days Ago ===

Applications and users can retrieve all **evidence files** using the ''report'' method.

- An enrollment with the status:
  - ''NEW''
  - ''STARTED''
  - ''CANCELED''  
  will return a **temporary** evidence file if **''draft = true''** is added to the request.

→ [[https://preprod.id360docaposte.com/static/swagger.html#/enrollment/enrollment_report_retrieve|See in Swagger]]

----

=== 📄 A Report Issued More Than 7 Days and Less Than 2 Months Ago ===

Users can retrieve all **finalized evidence files** (with a **verdict OK or KO**) using the ''report'' method.

----

=== 📄 A Report Issued More Than 2 Months Ago and Before the Archiving Expiration ===

Only **users** can access **archived reports** using the ''report/archive'' method.

  * An enrollment with a status of **CANCELED** or **FAILED** **is not archived**.
  * A **DELETED** enrollment (older than 2 months) is archived **only** if it had a final status of **OK** or **KO**.

----

=== 👥 Definition: Application vs User ===

**▶️ Retrieval via an application:**  
Login using your *application credentials* (application ID + password set at creation).

**▶️ Retrieval via a user:**  
Login using your *user credentials*:
  - Email address  
  - Personal password  
  - Two-factor authentication token (2FA)

----

=== 📄 Retrieving the PDF Report ===

See the dedicated method:  
[[https://preprod.id360docaposte.com/static/swagger.html#/enrollment/enrollment_proof_slip|Download the PDF report]]

====== 10. Retrieving the idClaim ======

[[https://preprod.id360docaposte.com/static/swagger.html#/enrollment/enrollment_idclaim|See the method in Swagger]]

----

=== 🔧 CURL Request – Production ===
<code javascript>
curl -X GET \
  "https://id360docaposte.com/api/1.0.0/enrollment/{id}/idclaim" \
  -H "accept: application/json" \
  -H "Authorization: Token 0123456789abcdef01234567"
</code>

----

=== 🔧 CURL Request – Preproduction ===
<code javascript>
curl -X GET \
  "https://preprod.id360docaposte.com/api/1.0.0/enrollment/{id}/idclaim" \
  -H "accept: application/json" \
  -H "Authorization: Token 0123456789abcdef01234567"
</code>

----

=== 🛠 Technical information ===

  * **''{id}''** : user file identifier, retrieved when it is created.
  * **Parameters** : none expected in this request.

----

=== ✅ Expected result ===

**HTTP Status** : ''200 OK''

**Response format** : ASIC-E

----

=== 💬 Notes ===

  * The connection token is **valid for 15 minutes**, renewed with each call made using this token.
  * If the token is expired or missing, you will receive a **401 Unauthorized** error.
  * As long as your token remains valid, **you must not reuse the ''login'' method**.
  * The token must be used in the header of subsequent calls as follows:

<code>
Authorization: Token token_returned_by_login
</code>