Recipe Executor

Endpoint Overview

POST /api/v1/ai-playground/execute-recipe

Description

This API endpoint executes a pre-configured AI recipe on an uploaded document (image or PDF). It processes the document according to the specified recipe and extracts structured data from vehicle registration certificates, returning key information such as registration numbers, owner details, and vehicle specifications in a standardized format.

Key Benefits

Extract structured data from vehicle registration documents automatically

Process both image and PDF formats with a single endpoint

Obtain comprehensive vehicle and owner information in a standardized JSON format

Reduce manual data entry errors and processing time

Use Cases

Automotive

Insurance

Government

Verify vehicle ownership during used car purchases

Automate vehicle registration data entry for insurance companies

Validate vehicle details for loan processing

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication (JWT format)
Content-Type	Yes	Must be `multipart/form-data` to support file upload

Request Body

Parameter	Type	Required	Description
recipe_id	String	Yes	Identifier for the recipe to be executed (obtained from "Create Recipe" endpoint)

Example Request

{
    "recipe_id": "rec_veh_reg_12345"
}

Process Response

Response Parameters

Parameter	Type	Description
data.doc_url	String	URL of the uploaded document
data.response.name	String	Full name of the member
data.response.member_id	String	Unique member identification number
data.response.phone	String	Member's contact phone number
data.response.address	String	Member's complete address
data.response.code	String	Optional code (if present)
data.response.hair	String	Optional hair detail (if present)
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
    "data": {
        "doc_url": "https://temp-surepass-bucket.s3.amazonaws.com/rahul/ai_playground/recipe_executor_dQDyzpegrhceeoZtycgu/recipe_doc_1747203185677188.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5JDBTSGYP%2F20250514%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20250514T061311Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=6d1b1710872b00ed6e08a098ce76e9de9859f61e6c56ccad71cbf721a219d7e0",
        "response": {
            "name": "Daniel Gallego",
            "member_id": "123-456-7890",
            "phone": "+123-456-7890",
            "address": "123 Anywhere St., Any City, ST 12345",
            "code": null,
            "hair": null
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Invalid Recipe

File Processing Error

{
    "status_code": 401,
    "success": false,
    "message": "Unauthorized access",
    "message_code": "unauthorized"
}

This error occurs when the JWT token is invalid, expired, or missing.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement token refresh mechanisms to handle token expiration

Validate file types and sizes before uploading to prevent security vulnerabilities

Implement proper error handling to avoid exposing sensitive information

User Experience Guidelines

Provide clear feedback to users during document upload and processing

Implement a timeout mechanism for long-running document processing

Allow users to review extracted information before submission

Provide options to manually correct any incorrectly extracted information

Code Samples

cURL

Python

Node.js

Related APIs

Create Recipe API: Used to create custom AI recipes before execution

List Recipes API: Retrieves available recipes for your account

Recipe Status API: Checks the status of a recipe execution

Compliance and Legal Considerations

When processing vehicle registration documents, ensure you have proper consent from the document owner. The extracted data may contain personally identifiable information (PII) and should be handled in accordance with relevant data protection regulations such as GDPR or local data privacy laws. Implement appropriate data retention and deletion policies for the extracted information.

{ "data": { "doc_url": "https://temp-surepass-bucket.s3.amazonaws.com/rahul/ai_playground/recipe_executor_dQDyzpegrhceeoZtycgu/recipe_doc_1747203185677188.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5JDBTSGYP%2F20250514%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20250514T061311Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=6d1b1710872b00ed6e08a098ce76e9de9859f61e6c56ccad71cbf721a219d7e0", "response": { "name": "Daniel Gallego", "member_id": "123-456-7890", "phone": "+123-456-7890", "address": "123 Anywhere St., Any City, ST 12345", "code": null, "hair": null } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Recipe Executor

Recipe Executor#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Recipe Executor

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples