Recipe Builder

Endpoint Overview

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

Description

The Recipe Builder API enables you to create intelligent document processing recipes by uploading a sample document. This endpoint initiates the AI-powered analysis of your document to automatically identify extractable fields, data types, and document structure. The API processes the uploaded file and generates a reusable recipe that can be applied to similar documents for automated data extraction.

This endpoint is the foundation of the AI Playground's document processing capability. By submitting a representative sample document (such as an ID card, invoice, certificate, or form), the system uses machine learning to understand the document layout and create an extraction template. You can optionally specify which page(s) to process in multi-page documents. The resulting recipe can then be used to process thousands of similar documents with consistent, accurate data extraction, eliminating manual data entry and reducing processing time from minutes to seconds.

Key Benefits

Automated Schema Generation: AI automatically identifies fields, labels, and data structure from your sample document without manual configuration

Selective Page Processing: Choose specific pages to analyze in multi-page documents, optimizing processing for relevant sections only

One-Time Setup: Create a recipe once from a sample document, then reuse it to process unlimited similar documents

Asynchronous Processing: Non-blocking operation allows you to submit documents and continue with other tasks while recipes are generated

Use Cases

Education & Academic

Financial Services

Healthcare & Insurance

Create recipes for student ID card processing to automate enrollment and registration systems

Build templates for transcript extraction to digitize academic records across multiple institutions

Generate schemas for certificate verification to validate educational credentials automatically

Develop extraction patterns for multi-page application forms, processing specific pages like personal information or academic history

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.app

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

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for API authentication. Format: `Bearer <JWT_TOKEN>`
Content-Type	Yes	Must be set to `multipart/form-data` for file upload

Request Body

Parameter	Type	Required	Description
file	file	Yes	The sample document file to be analyzed. Supported format: PDF. Maximum file size may vary based on your plan. The file should be a representative example of the document type you want to process.
page	string	No	Specific page number to process from the uploaded document. Valid range: 1 to 100. If not specified, all pages will be processed. Use this parameter to target specific pages in multi-page documents for more focused field extraction.

File Requirements:

Format: PDF only

Quality: Clear, readable text and well-structured layout

Content: Should contain all fields you want to extract in future documents

Pages: Single or multi-page documents supported (up to 100 pages)

Page Parameter Usage:

Omit the parameter to process all pages in the document

Specify a single page number (e.g., "1", "5", "23") to analyze only that page

Useful for large documents where only certain pages contain relevant data

Improves processing speed by focusing on specific pages

Example Request

Note: This endpoint uses multipart/form-data encoding for file upload. The file parameter should contain the binary file data with appropriate MIME type. The page parameter, when included, should be sent as form data along with the file.

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding the recipe creation metadata
data.recipe_id	string	Unique identifier for the newly created recipe. Use this ID to check processing status and execute the recipe on other documents.
data.pages	array	Array of page numbers detected or processed in the uploaded document (e.g., [1] for single page or specified page, [1, 2, 3] for multi-page)
data.use_pdf	boolean	Indicates whether the recipe is configured to process PDF documents. Always true for recipes created via this endpoint.
data.status	string	Current processing status. Possible values: "processing", "completed", "failed"
status_code	integer	HTTP status code (200 for successful submission)
success	boolean	Indicates if the request was successfully accepted
message	string	Human-readable message describing the result
message_code	string	Machine-readable code for the result status

Example Successful Response

{
    "data": {
        "recipe_id": "recipe_builder_mhCDembui",
        "pages": [
            1
        ],
        "use_pdf": true,
        "status": "processing"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Important Notes:

The initial response will have status "processing" as recipe generation is asynchronous

The pages array reflects the page(s) being processed - if page parameter was specified, only that page will be listed

Use the Fetch Build Recipe API with the returned recipe_id to check processing status

Recipe generation typically takes 30-90 seconds depending on document complexity and page count

Once status changes to "completed", the recipe is ready to use for document processing

Possible Error Responses

Authentication Error

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

This error indicates that the JWT token is missing, invalid, or expired. Generate a new token and retry the request.

Integration Best Practices

Security Recommendations

Secure File Handling: Validate and sanitize uploaded files on your application layer before forwarding to the API to prevent malicious file uploads

Token Security: Never expose JWT tokens in client-side code or public repositories. Use server-side proxies for API calls from web applications

HTTPS Only: Always use HTTPS endpoints to encrypt file data during transmission, especially for documents containing sensitive information

File Cleanup: Implement automatic deletion of temporary files after upload to prevent unauthorized access to sample documents

Access Logging: Maintain audit logs of recipe creation activities including user identity, timestamp, and document metadata for compliance tracking

Page Parameter Validation: Validate page numbers on the client side to ensure they're within the 1-100 range before making API requests

User Experience Guidelines

File Validation: Validate file format and size on the client side before upload to provide immediate feedback and reduce failed requests

Page Selection Interface: For multi-page documents, provide a page preview or selector to help users choose the relevant page for processing

Upload Progress: Display upload progress indicators for large files to keep users informed during the submission process

Processing Status: Implement polling or webhooks to monitor recipe generation status and notify users when recipes are ready

Sample Document Guidance: Provide clear instructions on selecting representative sample documents that contain all desired fields

Page Optimization Tips: Guide users to select pages with the most relevant data fields to improve extraction accuracy

Error Recovery: Offer actionable error messages and document quality tips when uploads fail due to unreadable or invalid files

Recipe Naming: After creation, allow users to assign meaningful names to recipes for easier identification and management

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

When uploading sample documents to create recipes, ensure compliance with data protection regulations including GDPR, CCPA, and local privacy laws. Sample documents should not contain real personally identifiable information (PII) unless you have explicit consent and legal basis for processing. Consider using anonymized or synthetic sample documents for recipe creation to avoid privacy concerns. The uploaded document is stored temporarily for processing and may be retained for quality assurance purposes - refer to Surepass's privacy policy for data retention details. Organizations in regulated industries must ensure that sample documents do not contain sensitive information protected by sector-specific regulations such as HIPAA (healthcare), GLBA (financial services), or FERPA (education). If using production data as samples, implement proper data anonymization techniques and obtain necessary approvals from your data protection officer or legal team. Maintain documentation of what types of documents are used for recipe creation and ensure appropriate data processing agreements are in place with Surepass. For documents containing children's information, ensure compliance with COPPA and other child protection regulations. The page parameter allows you to avoid processing unnecessary pages that may contain sensitive information - use this feature to minimize data exposure by targeting only relevant pages.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": { "recipe_id": "recipe_builder_mhCDembui", "pages": [ 1 ], "use_pdf": true, "status": "processing" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

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