> For the complete documentation index, see [llms.txt](https://docs.mindee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mindee.com/v1/off-the-shelf-products/carte-vitale-france-ocr.md). # Carte Vitale - FRANCE OCR Mindee’s **Carte Vitale - FRANCE** API uses deep learning to automatically, accurately, and instantaneously parse your card details. In under a second, the API extracts a set of data from your PDFs or photos of Carte Vitale, including: * Given Name(s) * Surname * Social Security Number * Issuance Date The **Carte Vitale - France** API supports the new and old format for all people in France. The cards of other nationalities and states are not supported with this model. ## Set up the API {% hint style="info" %} **Create an API key** To begin using the Mindee V1 OCR API, your first step is to [create your V1 API key](/v1/get-started/create-api-key.md). {% endhint %} 1. You'll need a french carte vitale. You can use one of the sample documents provided below.
2. Access your API by clicking on the **Carte Vitale - FRANCE** card in the **Document Catalog**
3. From the left navigation, go to [documentation](/v1/platform-ui-tour/api-documentation.md#api-reference) **> API Reference**, you'll find sample code in popular languages and command line. {% tabs %} {% tab title="Python" %} {% endtab %} {% tab %} ```python from mindee import Client, product, AsyncPredictResponse # Init a new client mindee_client = Client(api_key="my-api-key-here") # Load a file from disk input_doc = mindee_client.source_from_path("/path/to/the/file.ext") # Load a file from disk and enqueue it. result: AsyncPredictResponse = mindee_client.enqueue_and_parse( product.fr.HealthCardV1, input_doc, ) # Print a brief summary of the parsed data print(result.document) ``` {% endtab %} {% tab title="Node.js" %} ```javascript const mindee = require("mindee"); // for TS or modules: // import * as mindee from "mindee"; // Init a new client const mindeeClient = new mindee.v1.Client({ apiKey: "my-api-key-here" }); // Load a file from disk const inputSource = mindeeClient.docFromPath("/path/to/the/file.ext"); // Parse the file const apiResponse = mindeeClient.enqueueAndParse( mindee.v1.product.fr.HealthCardV1, inputSource ); // Handle the response Promise apiResponse.then((resp) => { // print a string summary console.log(resp.document.toString()); }); ``` {% endtab %} {% tab title=".NET" %} ```csharp using Mindee; using Mindee.Input; using Mindee.Product.Fr.HealthCard; string apiKey = "my-api-key-here"; string filePath = "/path/to/the/file.ext"; // Construct a new client MindeeClient mindeeClient = new MindeeClient(apiKey); // Load an input source as a path string // Other input types can be used, as mentioned in the docs var inputSource = new LocalInputSource(filePath); // Call the product asynchronously with auto-polling var response = await mindeeClient .EnqueueAndParseAsync(inputSource); // Print a summary of all the predictions System.Console.WriteLine(response.Document.ToString()); // Print only the document-level predictions // System.Console.WriteLine(response.Document.Inference.Prediction.ToString()); ``` {% endtab %} {% tab title="Ruby" %} ```ruby # # Install the Ruby client library by running: # gem install mindee # require 'mindee' # Init a new client mindee_client = Mindee::Client.new(api_key: 'my-api-key') # Load a file from disk input_source = mindee_client.source_from_path('/path/to/the/file.ext') # Parse the file result = mindee_client.parse( input_source, Mindee::Product::FR::HealthCard::HealthCardV1 ) # Print a full summary of the parsed data in RST format puts result.document # Print the document-level parsed data # puts result.document.inference.prediction ``` {% endtab %} {% tab title="Java" %} {% endtab %} {% tab %} ```java import com.mindee.MindeeClient; import com.mindee.input.LocalInputSource; import com.mindee.parsing.common.AsyncPredictResponse; import com.mindee.product.fr.healthcard.HealthCardV1; import java.io.File; import java.io.IOException; public class SimpleMindeeClient { public static void main(String[] args) throws IOException, InterruptedException { String apiKey = "my-api-key-here"; String filePath = "/path/to/the/file.ext"; // Init a new client MindeeClient mindeeClient = new MindeeClient(apiKey); // Load a file from disk LocalInputSource inputSource = new LocalInputSource(new File(filePath)); // Parse the file asynchronously AsyncPredictResponse response = mindeeClient.enqueueAndParse( HealthCardV1.class, inputSource ); // Print a summary of the response System.out.println(response.toString()); // Print a summary of the predictions // System.out.println(response.getDocumentObj().toString()); // Print the document-level predictions // System.out.println(response.getDocumentObj().getInference().getPrediction().toString()); // Print the page-level predictions // response.getDocumentObj().getInference().getPages().forEach( // page -> System.out.println(page.toString()) // ); } } ``` {% endtab %} {% tab title="Bash" %} ```bash API_KEY='my-api-key-here' ACCOUNT='mindee' ENDPOINT='french_healthcard' VERSION='1' FILE_PATH='/path/to/your/file.png' # Maximum amount of retries to get the result of a queue MAX_RETRIES=10 # Delay between requests DELAY=6 # Enqueue the document for async parsing QUEUE_RESULT=$(curl -sS --request POST \ -H "Authorization: Token $API_KEY" \ -H "Content-Type: multipart/form-data" \ -F "document=@$FILE_PATH" \ "https://api.mindee.net/v1/products/$ACCOUNT/$ENDPOINT/v$VERSION/predict_async") # Status code sent back from the server STATUS_CODE=$(echo "$QUEUE_RESULT" | grep -oP "[\"|']status_code[\"|']:[\s][\"|']*[a-zA-Z0-9-]*" | rev | cut --complement -f2- -d" " | rev) # Check that the document was properly queued if [ -z "$STATUS_CODE" ] || [ "$STATUS_CODE" -gt 399 ] || [ "$STATUS_CODE" -lt 200 ] then if [ -z "$STATUS_CODE" ] then echo "Request couldn't be processed." exit 1 fi echo "Error $STATUS_CODE was returned by API during enqueuing. " # Print the additional details, if there are any: ERROR=$(echo "$QUEUE_RESULT" | grep -oP "[\"|']error[\"|']:[\s]\{[^\}]*" | rev | cut --complement -f2- -d"{" | rev) if [ -z "$ERROR" ] then exit 1 fi # Details on the potential error: ERROR_CODE=$(echo "$ERROR" | grep -oP "[\"|']code[\"|']:[\s]\"[^(\"|\')]*" | rev | cut --complement -f2- -d"\"" | rev) MESSAGE=$(echo "$QUEUE_RESULT" | grep -oP "[\"|']message[\"|']:[\s]\"[^(\"|\')]*" | rev | cut --complement -f2- -d"\"" | rev) DETAILS=$(echo "$QUEUE_RESULT" | grep -oP "[\"|']details[\"|']:[\s]\"[^(\"|\')]*" | rev | cut --complement -f2- -d"\"" | rev) echo "This was the given explanation:" echo "-------------------------" echo "Error Code: $ERROR_CODE" echo "Message: $MESSAGE" echo "Details: $DETAILS" echo "-------------------------" exit 1 else echo "File sent, starting to retrieve from server..." # Get the document's queue ID QUEUE_ID=$(echo "$QUEUE_RESULT" | grep -oP "[\"|']id[\"|']:[\s][\"|'][a-zA-Z0-9-]*" | rev | cut --complement -f2- -d"\"" | rev) # Amount of attempts to retrieve the parsed document were made TIMES_TRIED=1 # Try to fetch the file until we get it, or until we hit the maximum amount of retries while [ "$TIMES_TRIED" -lt "$MAX_RETRIES" ] do # Wait for a bit at each step sleep $DELAY # Note: we use -L here because the location of the file might be behind a redirection PARSED_RESULT=$(curl -sS -L \ -H "Authorization: Token $API_KEY" \ "https://api.mindee.net/v1/products/$ACCOUNT/$ENDPOINT/v$VERSION/documents/queue/$QUEUE_ID") # Isolating the job (queue) & the status to monitor the document JOB=$(echo "$PARSED_RESULT" | grep -ioP "[\"|']job[\"|']:[\s]\{[^\}]*" | rev | cut --complement -f2- -d"{" | rev) QUEUE_STATUS=$(echo "$JOB" | grep -ioP "[\"|']status[\"|']:[\s][\"|'][a-zA-Z0-9-]*" | rev | cut --complement -f2- -d"\"" | rev) if [ "$QUEUE_STATUS" = "completed" ] then # Print the result echo "$PARSED_RESULT" # Optional: isolate the document: # DOCUMENT=$(echo "$PARSED_RESULT" | grep -ioP "[\"|']document[\"|']:[\s].*([\"|']job[\"|'])" | rev | cut -f2- -d"," | rev) # echo "{$DOCUMENT}" # Remark: on compatible shells, fields can also be extracted through the use of tools like jq: # DOCUMENT=$(echo "$PARSED_RESULT" | jq '.["document"]') exit 0 fi TIMES_TRIED=$((TIMES_TRIED+1)) done fi echo "Operation aborted, document not retrieved after $TIMES_TRIED tries" exit 1 ``` {% endtab %} {% tab title="PHP" %} ```php sourceFromPath("/path/to/the/file.ext"); // Parse the file asynchronously $apiResponse = $mindeeClient->enqueueAndParse(HealthCardV1::class, $inputSource); echo $apiResponse->document; ``` {% endtab %} {% endtabs %} * Replace **my-api-key-here** with your new API key, or use the **select an API key** feature and it will be filled automatically. * Copy and paste the sample code of your desired choice in your application, code environment, terminal etc. * Replace `/path/to/the/file.ext` with the path to your input document. {% hint style="warning" %} Remember to replace with your V1 API key. {% endhint %} 4. Run your code. You will receive a JSON response with the document details. ## API Response Here is the full JSON response you get when you call the API: ```json { "api_request": { "error": {}, "resources": [ "document", "job" ], "status": "success", "status_code": 200, "url": "https://api.mindee.net/v1/products/mindee/french_healthcard/v1/documents/1ec5aff1-ef20-4744-bf7e-fe03464192f3" }, "document": { "id": "1ec5aff1-ef20-4744-bf7e-fe03464192f3", "inference": { "extras": {}, "finished_at": "2024-10-28T10:07:18.627000", "is_rotation_applied": true, "pages": [ { "extras": {}, "id": 0, "orientation": { "value": 0 }, "prediction": {} } ], "prediction": { ... }, "processing_time": 2.084, "product": { "features": [ "given_names", "surname", "social_security", "issuance_date" ], "name": "mindee/french_healthcard", "type": "standard", "version": "1.0" }, "started_at": "2024-10-28T10:07:16.391000" }, "n_pages": 1, "name": "CarteVitale2 (1).jpg" }, "job": { "available_at": "2024-10-28T10:07:18.636000", "error": {}, "id": "097af697-b4dc-4a4a-9374-9e64fb009b01", "issued_at": "2024-10-28T10:07:16.391000", "status": "completed" } } ``` You can find the prediction within the `prediction` key found in **`document > inference > prediction` for document-level predictions**: it contains the different fields extracted at the document level, meaning that for multi-pages PDFs, we reconstruct a single object using all the pages. Each predicted field may contain one or several values: * a `polygon` highlighting the information location * a `page_id` where the information was found (document level only) ```json { "api_request": { ... }, "document": { ... "prediction": { "given_names": [ { "page_id": 0, "polygon": [ [ 0.282, 0.671 ], [ 0.441, 0.671 ], [ 0.441, 0.709 ], [ 0.282, 0.709 ] ], "value": "NATHALIE" } ], "issuance_date": { "page_id": 0, "polygon": [ [ 0.443, 0.438 ], [ 0.605, 0.438 ], [ 0.605, 0.475 ], [ 0.443, 0.475 ] ], "value": "2007-01-01" }, "social_security": { "page_id": 0, "polygon": [ [ 0.282, 0.838 ], [ 0.616, 0.838 ], [ 0.616, 0.873 ], [ 0.282, 0.873 ] ], "value": "2 69 05 49 588 157 80" }, "surname": { "page_id": 0, "polygon": [ [ 0.284, 0.727 ], [ 0.422, 0.727 ], [ 0.422, 0.766 ], [ 0.284, 0.766 ] ], "value": "DURAND" } }, ... } } ``` ## Detailed Field Information Depending on the field type specified, additional attributes can be extracted from the Carte Vitale -FRANCE card object. Using the above example the following are the basic fields that can be extracted. * [Given Name(s)](#given-names) * [Surname](#surname) * [Social Security Number](#social-security-number) * [Issuance Date](#issuance-date) ### Given Name(s) * given\_names: The given names of the card holder. ```json { "given_names": [ { "page_id": 0, "polygon": [[0.282,0.671],[0.441,0.671],[0.441,0.709],[0.282,0.709]], "value": "NATHALIE" } ] } ``` ### Surname * **surname**: The surname of the card holder. ```json { "surname": { "page_id": 0, "polygon": [[0.284,0.727],[0.422,0.727],[0.422,0.766],[0.284,0.766]], "value": "DURAND" } } ``` ### Social Security Number * **social\_security**: The social security number of the card holder. ```json { "social_security": { "page_id": 0, "polygon": [[0.282,0.838],[0.616,0.838],[0.616,0.873],[0.282,0.873]], "value": "2 69 05 49 588 157 80" } } ``` ### Issuance Date * **issuance\_date**: The date when the carte vitale was issued. ```json { "issuance_date": { "page_id": 0, "polygon": [[0.443,0.438],[0.605,0.438],[0.605, 0.475 ], [ 0.443, 0.475 ] ], "value": "2007-01-01" } } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.mindee.com/v1/off-the-shelf-products/carte-vitale-france-ocr.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.