Create Recipe

Endpoint Overview

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

Description

This API endpoint enables you to create a customized recipe for extracting specific information from images or PDF documents. By defining the data fields (keys) you need to extract and providing a descriptive prompt, the system generates a unique recipe ID that can be used for consistent document processing. This recipe-based approach allows you to efficiently process multiple documents with the same structure while maintaining consistent extraction parameters.

Key Benefits

Create reusable extraction templates for consistent document processing

Customize extraction fields based on specific business requirements

Reduce processing time by using pre-defined recipes for similar documents

Improve extraction accuracy with targeted prompts for specific document types

Use Cases

Automotive

Financial Services

Government & Compliance

Extract vehicle registration details for fleet management systems

Process vehicle ownership transfers with automated document verification

Validate vehicle documentation during insurance underwriting

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 authentication using JWT
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
name	String	Yes	Name of the recipe for identification purposes
keys	Object	Yes	Object containing the fields to be extracted from documents
model	Enum	No	AI Model (choices openai_mini, openai_v4, gemini)
tag	Enum	No	Tag (choices general, fintech, healthcare, id, verification, medical, logistics, travel, real_estate)
description	String	Yes	Detailed description of what information should be extracted from the document
preference_type	Enum	No	Preference Type (choices latency, price, throughput)
pages	Integer	No	Pages To Process
use_pdf	Boolean	No	Use PDF

keys Object Parameters

Parameter	Type	Description
name	String	Name
member_id	String	Member ID
phone	String	Phone
address	String	Vehicle owner's full address

Example Request

{
    "keys": {
        "name": "str",
        "member_id": "int",
        "phone": "str",
        "address": "str"
    },
    "description": "The image displays a student ID card from the Ingoude Academy. It includes details like name, member ID, phone number, and address.",
    "name": "Student ID Card Details"
}

Process Response

Response Parameters

Parameter	Type	Description
recipe_id	String	Recipe ID
keys	Object	Keys
description	String	Description
model	String	Model
name	String	Name
created_at	String	Created At (YYYY-MM-DD format)
tag	String	Recipe Tag
preference_type	String	Preference Type (optional)
pages	List	List of page numbers
use_pdf	Boolean	Use PDF
doc_url	String	Document URL

Example Successful Response

{
    "data": {
        "recipe_id": "recipe_fxwFeYqwpVzjunaDbAEM",
        "keys": {
            "name": "str",
            "member_id": "int",
            "phone": "str",
            "address": "str"
        },
        "description": "The image displays a student ID card from the Ingoude Academy. It includes details like name, member ID, phone number, and address.",
        "model": null,
        "name": "Student ID Card Details",
        "created_at": "2025-05-14",
        "tag": "general",
        "preference_type": "latency",
        "pages": [],
        "use_pdf": false,
        "doc_url": null
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Validation Error

{
    "status_code": 401,
    "success": false,
    "message": "Unauthorized access. Invalid or missing authentication token.",
    "message_code": "unauthorized"
}

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

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

Use HTTPS for all API communications to ensure data encryption in transit

Implement proper error handling to avoid exposing sensitive information

User Experience Guidelines

Create descriptive recipe names that clearly identify the document type

Provide detailed descriptions that specify exactly what information to extract

Include all relevant fields in the keys object, even if some are optional

Test recipes with sample documents to ensure accurate extraction before production use

Code Samples

cURL

Python

Node.js

Related APIs

Process Document with Recipe: Use a created recipe to process documents

List Recipes: Retrieve all recipes created by your account

Get Recipe Details: Retrieve detailed information about a specific recipe

Delete Recipe: Remove a recipe that is no longer needed

Compliance and Legal Considerations

When extracting personal information from documents, ensure compliance with relevant data protection regulations such as GDPR, CCPA, or local data privacy laws. Implement appropriate data retention policies and obtain necessary consent before processing personal information. Vehicle registration documents may contain sensitive personal data that requires special handling under privacy regulations.

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/create-recipe' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "keys": { "name": "str", "member_id": "int", "phone": "str", "address": "str" }, "description": "The image displays a student ID card from the Ingoude Academy. It includes details like name, member ID, phone number, and address.", "name": "Student ID Card Details" }'

{ "data": { "recipe_id": "recipe_fxwFeYqwpVzjunaDbAEM", "keys": { "name": "str", "member_id": "int", "phone": "str", "address": "str" }, "description": "The image displays a student ID card from the Ingoude Academy. It includes details like name, member ID, phone number, and address.", "model": null, "name": "Student ID Card Details", "created_at": "2025-05-14", "tag": "general", "preference_type": "latency", "pages": [], "use_pdf": false, "doc_url": null }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Create Recipe

Create Recipe#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

keys Object Parameters#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Create Recipe

Description

Use Cases

Technical Implementation

Request Headers

Request Body

keys Object Parameters

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples