[[:guide_du_developpeur_capture|FranΓ§ais]] | [[:en:guide_du_developpeur_capture|English]] ---- ====== Developer Guide – ID360 Capture ====== === 🎯 The ID360 solution allows you to: === * βœ… Manage the **identification** and **authentication** of users in your business service. * πŸ—‚οΈ (Optional) **Collect**, **store**, and **verify the authenticity** of supporting documents. * 🎨 Customize a **user interface** to meet your needs. ---- === πŸ”— Swagger Access === * **[[https://preprod.id360docaposte.com/static/swagger.html|Preproduction Swagger]]** * **[[https://id360docaposte.com/static/swagger.html|Production Swagger]]** ---- === πŸ”§ Main API Operations === - **API Login**: This call provides a valid token for 15 minutes, allowing access to other API methods. - **Create a user folder**: Returns a folder ID and an API key (api_key), essential for the next steps. - **Data comparison (optional)**: You may compare expected data with extracted identity data. - **Redirect user to the user interface (UI)**: Use the API key to redirect the user to their enrollment journey. - **Retrieve report**: Retrieve the user's folder report using the folder ID, with status and technical/verification info. - **Retrieve documents**: Optionally, retrieve identity and supporting documents submitted by the user. - **Retrieving the idClaim (optional)**: Only in the case of advanced electronic signature, returns an ASIC-E. === πŸ”§ Additional options and tools === * **Run ID360 in a WebView (optional)**: outside processes offering La Poste Digital Identity * **Interrupt a user folder** : To invalidate an identification URL and force the closure of a file in the case of an identification process that has not been started or is incomplete. ---- πŸ“˜ **To continue reading this guide, you must first create at least one process and one application.** If not already done, we recommend checking 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 === curl -X POST "https://id360docaposte.com/api/1.0.0/user/login/" \ -H "accept: application/json" \ -d '{ "username": "string", "password": "string", "token": "string" }' === πŸ”§ RequΓͺte CURL – PrΓ©production === curl -X POST "https://preprod.id360docaposte.com/api/1.0.0/user/login/" \ -H "accept: application/json" \ -d '{ "username": "string", "password": "string", "token": "string" }' ---- === πŸ“₯ 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**: { "token": "0123456789abcdef01234567" } ---- === πŸ’¬ 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**: Authorization: Token 0123456789abcdef01234567 ---- === 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**: Authorization: Token 0123456789abcdef01234567 ---- === βœ… 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. Create a user folder ====== [[https://preprod.id360docaposte.com/static/swagger.html#/process/process_enrollment_create|See the method in Swagger]] ---- === πŸ”§ CURL Request – Production === curl -X POST \ "https://id360docaposte.com/api/1.0.0/process/{id}/enrollment" \ -H "Authorization: Token 0123456789abcdef01234567" ---- === πŸ”§ CURL Request – Preproduction === curl -X POST \ "https://preprod.id360docaposte.com/api/1.0.0/process/{id}/enrollment" \ -H "Authorization: Token 0123456789abcdef01234567" ---- === πŸ›  URL Notes === Replace the ''{id}'' part with the **UUID of a process**. Process objects are configurable via the admin UI (their UUID is displayed there). ---- === πŸ“₯ Expected Body === { "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"}] }], "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" } ---- === πŸ“ Field Details === * **''browser_callback_url''**: required – URL triggered by the user's browser at the end of the process (used only for redirection purposes). * **''client_reference''**: optional – Allows linking to an internal identifier from your system. Useful for cross-referencing in case of cancellation or failure. * **''callback_endpoints''**: required – A callback endpoint enables ID360 to notify your system when an enrollment reaches a specific status (e.g., failure, cancellation, completion), via an HTTP POST request to the URL you provided. Headers are optional and can be used as identification headers when receiving callbacks. * **''last_name, first_name, address_line_1/2/3, zip_code, city, country, phone_number, email''**: optional – User information is provided for **informational purposes only** (no validation is performed). * **''group''**: optional – Allows consumption exports based on user-defined groups. > For more information about callback_endpoints, see [[https://wiki.id360docaposte.com/doku.php?id=en:guide_callbacks|this dedicated guide]]. ---- === πŸ“€ Expected Result (example) === **HTTP Status**: ''200 OK'' { "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"}] }] } ---- === πŸ’¬ Notes === * This call **must be performed server-side**, never from the user's browser. * ⚠️ **It is essential to keep both the enrollment ''id'' and the ''api_key''** for the next steps in the process. ====== 3. Data Comparison (optional) ====== In the process configuration, it is essential to select **at least one data field to compare**. To do this, 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 === curl -X POST \ "https://id360docaposte.com/api/1.0.0/enrollment/{id}/control/data/{data_name}/?locked=true" \ -H "accept: application/json" \ -H "Authorization: Token 0123456789abcdef01234567" ---- === πŸ”§ CURL Request – Preproduction === curl -X POST \ "https://preprod.id360docaposte.com/api/1.0.0/enrollment/{id}/control/data/{data_name}/?locked=true" \ -H "accept: application/json" \ -H "Authorization: Token 0123456789abcdef01234567" ---- === πŸ›  Technical Information === * **''{id}''**: enrollment ID, obtained when creating the user enrollment. * **''{data_name}''**: name of the data field to be compared. - Examples: - ''name'' β†’ last name - ''first_name'' β†’ first name - ''birth_date'' β†’ date of birth * To check 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) | | ''auto'' | false | The behavior depends on the type of data requested. For the ''phone_number'' data, the OTP SMS is triggered **upon page load**. Otherwise, the OTP code is sent **immediately upon the API request**. | ---- === πŸ“€ Expected Body === The body must simply contain **the data to be checked**, in plain format (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**. ====== 4. Redirecting the User to the UI ====== This step must be performed **directly in the user's browser**. Using the ''api_key'' obtained during the user enrollment creation, you can redirect the user to the data entry interface using the following URL: ---- === 🌐 Production Environment === https://www.id360docaposte.com/static/process_ui/index.html#/enrollment/api_key_from_previous_step ---- === πŸ§ͺ Preproduction Environment === https://preprod.id360docaposte.com/static/process_ui/index.html#/enrollment/api_key_from_previous_step ---- === ℹ️ Notes === * This URL **must be opened in the end user's browser**. * Replace **''api_key_from_previous_step''** with the actual value received when the enrollment was created (field ''api_key'' in the response). ==== When the user has completed their identification process ==== A token is appended as a parameter to the redirection URL (browser callback) when the user is redirected. For example: https://browsercallback.fr?token=2c4a10812ed36dd6d6de2e3c4751ff20e277b4fe41b557dcebb31f5f5a66550815163de0f4e51ac4619a14be98da2de156914a87bdecccba41e9be357aaa2582 This token can be used to call the following method: https://preprod.id360docaposte.com/static/swagger.html#/enrollment/enrollment_status_retrieve This method retrieves the enrollment associated with the token present in the callback URL. It can only be invoked **once per enrollment**, after which the token is automatically invalidated. Note that this is a **fingerprint of the enrollment**, not a full identification report like the one obtained via the "report" parameter (an example is available in Swagger). Even if you do not use this token, the enrollment status will still be sent through the callback URL (see next step). ====== 5 Retrieve report ====== ===== 5.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 === curl -X GET \ "https://id360docaposte.com/api/1.0.0/enrollment/{id}/report" \ -H "accept: application/json" \ -H "Authorization: Token 0123456789abcdef01234567" ---- === πŸ”§ CURL Request – Preproduction === curl -X GET \ "https://preprod.id360docaposte.com/api/1.0.0/enrollment/{id}/report" \ -H "accept: application/json" \ -H "Authorization: Token 0123456789abcdef01234567" ---- === πŸ›  Technical Information === * **''{id}''**: ID of the user enrollment, obtained during its creation. * **Parameters**: no parameters are required for this request. ---- === βœ… Expected Result === **HTTP Status**: ''200 OK'' **Response format**: JSON ---- === πŸ’¬ Notes === * This call must be made **by your server**, **never from the user's browser**. * The access token is **valid for 15 minutes**, renewed with each call using the token. * If the token is missing or expired, a **401 Unauthorized error** will be returned. * As long as your token is valid, **you should not reuse the ''login'' method**. * The token must be included in the header of subsequent requests as follows: Authorization: Token the_token_returned_by_login ===== 5.2 Retrieving the Report from the Admin Platform ===== The report is also available in the console, under the β€œUser Enrollments” tab, for a period of two months. The identifier corresponds to the enrollment ID generated at the end of step 2. By selecting β€œView details,” you can access the identification report and download the evidence file in JSON format at the bottom of the page. ===== 5.3 Specifics ===== ---- === πŸ“„ 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''** indicating the completion of the enrollment process. **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** via the ''report'' method. - A file with the status: - ''NEW'' - ''STARTED'' - ''CANCELED'' will return a **temporary** evidence file when using the **''draft = true''** parameter. β†’ [[https://preprod.id360docaposte.com/static/swagger.html#/enrollment/enrollment_report_retrieve|See in Swagger]] ---- === πŸ“„ A Report Issued More Than 7 Days Ago and Less Than 2 Months Ago === Users can retrieve all **finalized evidence files** (with a **verdict OK or KO**) via the ''report'' method. ---- === πŸ“„ A Report Issued More Than 2 Months Ago and Before the Archiving Expiration Date === Only **users** can access **archived reports** via the ''report/archive'' method. * A file with status **CANCELED** or **FAILED** **is not archived**. * A **DELETED** file (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 defined 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]] ====== 6. Retrieving documents ====== You can use the API to retrieve **analyzed identity documents** and, if configured, **collected documents**. This is possible **up to 7 days after enrollment**. [[https://preprod.id360docaposte.com/static/swagger.html#/document/document_file_contents|See the method in Swagger]] ---- === πŸ”§ CURL Request – Production === curl -X 'GET' \ 'https://id360docaposte.com/api/1.0.0/document/{id_document}/file_contents/?page_number={page_number}' \ -H 'accept: application/octet_stream' \ -H 'Authorization: Token 4550d727f89d76dc0b07917461a16710141d101e0796ec644c' ---- === πŸ”§ CURL Request – Preproduction === curl -X 'GET' \ 'https://preprod.id360docaposte.com/api/1.0.0/document/{id_document}/file_contents/?page_number={page_number}' \ -H 'accept: application/octet_stream' \ -H 'Authorization: Token 4550d727f89d76dc0b07917461a16710141d101e0796ec644c' ---- === πŸ“„ Notes === * The document is returned **directly in the response**. * To get **both front and back** of an ID document, call the method twice with a different **''page_number''**: - ''page_number=0'' β†’ front - ''page_number=1'' β†’ back ---- === πŸ“ Example of extraction from a JSON report === "documents": { "identity": [{ "name": "id_document_image", "files": [ { "url": "https://preprod.id360docaposte.com/api/1.0.0/document/354746/file_contents/?page_number=0" }, { "url": "https://preprod.id360docaposte.com/api/1.0.0/document/354746/file_contents/?page_number=1" } ] }] } * The document ID is **''354746''**. * ''page 0'' = front / ''page 1'' = back ---- === πŸ“š Types of Documents That Can Be Retrieved === ^ Document Type ^ JSON Key (name) ^ | **Identity Document (SVID)** | ''"documents": { "identity": [{ "name": "id_document_image", "files": [{"url": xxxxxxxxxxxxxxx}, {"url": xxxxxxxxxxxxxxx}]}'' | | **Identity Document (PVID)** | ''"documents": {"other": [{ "name": "ar24_in_front", "files": [{"url": xxxxxxxxxxxxxxx}], [{ "name": "ar24_in_back", "files": [{"url": xxxxxxxxxxxxxxx}]}'' | | **Identity Document with MIE** | ''"documents": {"identity": [{ "name": "idd", "files": [{"url": xxxxxxxxxxxxxxx}]}]}'' | | **Bank Account Details (RIB)** | ''"documents": { "bank_details": [{ "name": "bank_details_image", "files": [{"url": xxxxxxxxxxxxxxx}]}'' | | **Tax Notice** | ''"documents": { "income_tax": [{ "name": "income_tax_notice_image", "files": [{"url": xxxxxxxxxxxxxxx}]}'' | | **Company Registration (KBIS)** | ''"documents": { "kbis": [{ "name": "kbis_image", "files": [{"url": xxxxxxxxxxxxxxx}]}'' | | **Payslip** | ''"documents": { "pay_slip": [{ "name": "pay_slip_image", "files": [{"url": xxxxxxxxxxxxxxx}]}'' | | **Property Tax** | ''"documents": { "property_tax": [{ "name": "property_tax_notice_image", "files": [{"url": xxxxxxxxxxxxxxx}]}'' | | **Selfie / Uploaded Photo** | ''"documents": { "selfie": [{ "name": "selfie_image_upload", "files": [{"url": xxxxxxxxxxxxxxx}]}'' | | **Selfie / Processed Photo** | ''"documents": { "selfie": [{ "name": "selfie_image", "files": [{"url": xxxxxxxxxxxxxxx}]}'' | | **Health Insurance Card** | ''"documents": { "health_insurance_card": [{ "name": "health_insurance_card_image", "files": [{"url": xxxxxxxxxxxxxxx}]}'' | | **Social Security Card** | ''"documents": { "social_security_card": [{ "name": "social_security_card_image", "files": [{"url": xxxxxxxxxxxxxxx}]}'' | | **Proof of Address** | ''"documents": { "proof_of_address": [{ "name": "proof_of_address_image", "files": [{"url": xxxxxxxxxxxxxxx}]}'' | | **Car Registration** | ''"documents": { "car_registration": [{ "name": "car_registration_image", "files": [{"url": xxxxxxxxxxxxxxx}]}'' | | **Liveness** | ''"documents": { "liveness": [{"name": "liveness_video$0", "files": [{"url": "xxxxxxxxxxxxxxx"}]},{"name": "liveness_video$1","files": [{"url": "xxxxxxxxxxxxxxx"}]}]'' | ====== 7. Retrieving the idClaim ====== [[https://preprod.id360docaposte.com/static/swagger.html#/enrollment/enrollment_idclaim|See the method in Swagger]] ---- === πŸ”§ CURL Request – Production === curl -X GET \ "https://id360docaposte.com/api/1.0.0/enrollment/{id}/idclaim" \ -H "accept: application/json" \ -H "Authorization: Token 0123456789abcdef01234567" ---- === πŸ”§ CURL Request – Preproduction === curl -X GET \ "https://preprod.id360docaposte.com/api/1.0.0/enrollment/{id}/idclaim" \ -H "accept: application/json" \ -H "Authorization: Token 0123456789abcdef01234567" ---- === πŸ›  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: Authorization: Token token_returned_by_login ====== Conditions for running ID360 in a WebView ====== The following permissions must be enabled on the application side (Android or iOS): * Camera access * Gyroscope access * File access (for document import) And also: * Enable JavaScript * On Android, initialize the WebView with the **activity context** (and not the application's global context) to ensure proper functioning of elements such as drop-down menus. ====== Discontinue an Enrollment ====== [[https://preprod.id360docaposte.com/static/swagger.html#/Enrollment%20Control/control_discontinue|View the method in Swagger]] ---- === πŸ”§ CURL Request – Production === curl -X GET \ "https://id360docaposte.com/api/1.0.0/enrollment/{id}/control/discontinue" \ -H "Authorization: Token 0123456789abcdef01234567" ---- === πŸ”§ CURL Request – Preproduction === curl -X GET \ "https://preprod.id360docaposte.com/api/1.0.0/enrollment/{id}/control/discontinue" \ -H "Authorization: Token 0123456789abcdef01234567" ---- === πŸ›  Technical Information === * **''{id}''**: user enrollment identifier, retrieved during its creation. * **Parameters**: no parameters are expected in this request. ---- === βœ… Expected Result === **HTTP Status**: ''204 No Content'' ---- === πŸ’¬ Notes === The enrollment status will be changed to **DISCONTINUED**.