Recipe Executor

Endpoint Overview

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

Description

This API endpoint executes a pre-configured AI recipe on a document (image or PDF). It processes the document according to the specified recipe and extracts structured data, returning key information in a standardized format. You can provide the document via file upload, base64-encoded string, or a publicly accessible URL.

Key Benefits

Extract structured data from documents automatically

Process both image and PDF formats with a single endpoint

Flexible input options — upload a file, send a base64 string, or provide a document URL

Obtain comprehensive 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	`multipart/form-data` when sending a file; `application/json` when sending base64 or link

Request Body

Parameter	Type	Required	Description
recipe_id	String	Yes	Identifier for the recipe to be executed (obtained from the "Create Recipe" endpoint)
file	File	No	The document file to be processed. Supported formats: PDF, JPG, JPEG, PNG.
base64	String	No	Base64-encoded string of the document.
link	String	No	Publicly accessible URL pointing to the document file. The URL must be reachable and return a valid PDF or image file.

Input Requirement

While file, base64, and link are each individually marked as not required, you must provide exactly one of the three as the document input source. If none are provided or multiple are provided, the request will fail.

Input Priority & Guidelines:

file: Best suited for direct uploads from user-facing applications. Use multipart/form-data content type.

base64: Ideal for server-to-server integrations where the document is already in memory or stored as a base64 string. Use application/json content type.

link: Convenient when documents are hosted on cloud storage (S3, GCS, Azure Blob) or accessible via public URLs. Use application/json content type. Ensure the link is accessible and not behind authentication.

Example Requests

Using file upload:

Using base64:

{
  "recipe_id": "rec_veh_reg_12345",
  "base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..."
}

Using link:

{
  "recipe_id": "rec_veh_reg_12345",
  "link": "https://example.com/documents/registration_certificate.pdf"
}

Process Response

Response Parameters

Parameter	Type	Description
data.doc_url	String	URL of the uploaded/processed 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

Missing Input 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

When using the link parameter, ensure the URL uses HTTPS and does not expose sensitive data through query parameters

When using the base64 parameter, validate the encoded string on the server side before forwarding to the API

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

When offering multiple input methods, clearly indicate the recommended approach for each use case (e.g., file upload for end users, base64 for backend integrations, link for cloud-hosted documents)

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.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/ai-playground/execute-recipe' \ --header 'Authorization: Bearer <token>' \ --form 'file=@""' \ --form 'recipe_id=""' \ --form 'link=""' \ --form 'base64=""'

{ "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" }

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Requests#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses