(Rest Smart Connector 🔌) IDP Generic - EEA and EFTA Driving Licence

IDP Generic - EEA and EFTA Driving Licence API Documentation

Overview and Purpose of the API

The IDP Generic - EEA and EFTA Driving Licence API provides a set of endpoints to facilitate the submission and retrieval of driving licence document execution data. This API is designed to support organizations in processing and managing driving licence information for EEA (European Economic Area) and EFTA (European Free Trade Association) regions. It allows users to submit document execution requests and retrieve the status and details of these executions.

This API is particularly useful for organizations that need to automate the processing of driving licence data, ensuring secure and efficient handling of sensitive information.

Authentication Requirements and Security Details

The API uses OAuth 2.0 for authentication and requires a bearer token to access its endpoints. The following details are relevant for authentication:

• Authorization URL: Not provided in the input.
• Access Token URL: https://anypoint.mulesoft.com/accounts/api/v2/oauth2/token
• Scopes: None specified.
• Authorization Grants: Implicit.

To access the API, include the bearer token in the Authorization header of your requests:

Authorization: Bearer <your_access_token>

Base URL and Environments

The base URL for the API is:

https://idp-rt.us-east-1.anypoint.mulesoft.com

All endpoints are prefixed with this base URL. Ensure that you use the correct base URL when making API requests.

Detailed Endpoint Documentation

1. Submit Document Execution

Endpoint: POST /api/v1/organizations/eca25329-9592-4ff1-9054-1b08d103b991/actions/d9402a9d-86d4-4797-b47e-76a00e04092d/versions/1.0.0/executions

Description: Submits an action version document execution.

Authentication: Secured with OAuth 2.0 (Bearer Token).

Request

• Method: POST
• Content-Type: multipart/form-data
• Request Body: The request body must include the document data in a multipart form. The exact structure of the request body is not defined in the input.

Response

• Status Code: 201 Created
• Response Body:

  {
    "id": "string",
    "documentName": "string",
    "status": "string"
  }

Example Request

POST /api/v1/organizations/eca25329-9592-4ff1-9054-1b08d103b991/actions/d9402a9d-86d4-4797-b47e-76a00e04092d/versions/1.0.0/executions HTTP/1.1
Host: idp-rt.us-east-1.anypoint.mulesoft.com
Authorization: Bearer <your_access_token>
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="file"; filename="document.pdf"
Content-Type: application/pdf

<binary content>
--boundary--

Example Response

{
  "id": "12345",
  "documentName": "Driving_Licence.pdf",
  "status": "Submitted"
}

2. Get Document Execution Status

Endpoint: GET /api/v1/organizations/eca25329-9592-4ff1-9054-1b08d103b991/actions/d9402a9d-86d4-4797-b47e-76a00e04092d/versions/1.0.0/executions/{executionId}

Description: Retrieves the status and details of a specific document execution.

Authentication: Secured with OAuth 2.0 (Bearer Token).

Request

• Method: GET
• Path Parameters:
  • executionId (string): The unique identifier of the document execution.
• Query Parameters: None.

Response

• Status Code: 200 OK
• Response Body:

  {
    "pages": [
      {
        "page": "string",
        "prompts": {
          "date_of_issue": {
            "answer": {
              "value": "string",
              "geometry": {
                "height": 0,
                "left": 0,
                "width": 0,
                "top": 0
              },
              "confidenceScore": 0
            },
            "source": "string",
            "prompt": "string"
          },
          "date_of_expiry": {
            "answer": {
              "value": "string",
              "geometry": {
                "height": 0,
                "left": 0,
                "width": 0,
                "top": 0
              },
              "confidenceScore": 0
            },
            "source": "string",
            "prompt": "string"
          }
        }
      }
    ],
    "id": "string",
    "documentName": "string",
    "prompts": {},
    "status": "string"
  }

Example Request

GET /api/v1/organizations/eca25329-9592-4ff1-9054-1b08d103b991/actions/d9402a9d-86d4-4797-b47e-76a00e04092d/versions/1.0.0/executions/12345 HTTP/1.1
Host: idp-rt.us-east-1.anypoint.mulesoft.com
Authorization: Bearer <your_access_token>

Example Response

{
  "pages": [
    {
      "page": "1",
      "prompts": {
        "date_of_issue": {
          "answer": {
            "value": "2023-01-01",
            "geometry": {
              "height": 10,
              "left": 5,
              "width": 15,
              "top": 20
            },
            "confidenceScore": 0.98
          },
          "source": "OCR",
          "prompt": "Date of Issue"
        },
        "date_of_expiry": {
          "answer": {
            "value": "2033-01-01",
            "geometry": {
              "height": 10,
              "left": 5,
              "width": 15,
              "top": 40
            },
            "confidenceScore": 0.95
          },
          "source": "OCR",
          "prompt": "Date of Expiry"
        }
      }
    }
  ],
  "id": "12345",
  "documentName": "Driving_Licence.pdf",
  "status": "Completed"
}

Error Handling and Status Codes

The API uses standard HTTP status codes to indicate the success or failure of a request. Below are the possible status codes:

Best Practices for Implementation

• Authentication: Always ensure that the bearer token is valid and included in the Authorization header.
• Error Handling: Implement robust error handling to manage different status codes gracefully.
• Data Validation: Validate the request body and parameters before sending the request to avoid unnecessary errors.
• Secure Data: Handle sensitive data, such as driving licence details, securely and in compliance with data protection regulations.

Sample Code Snippets

Submitting a Document Execution (Python)

import requests

url = "https://idp-rt.us-east-1.anypoint.mulesoft.com/api/v1/organizations/eca25329-9592-4ff1-9054-1b08d103b991/actions/d9402a9d-86d4-4797-b47e-76a00e04092d/versions/1.0.0/executions"
headers = {
    "Authorization": "Bearer <your_access_token>"
}
files = {
    "file": ("document.pdf", open("document.pdf", "rb"), "application/pdf")
}

response = requests.post(url, headers=headers, files=files)
print(response.json())

Retrieving Document Execution Status (Python)

import requests

execution_id = "12345"
url = f"https://idp-rt.us-east-1.anypoint.mulesoft.com/api/v1/organizations/eca25329-9592-4ff1-9054-1b08d103b991/actions/d9402a9d-86d4-4797-b47e-76a00e04092d/versions/1.0.0/executions/{execution_id}"
headers = {
    "Authorization": "Bearer <your_access_token>"
}

response = requests.get(url, headers=headers)
print(response.json())