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 provide the document via file upload, base64-encoded string, or a publicly accessible URL. You can also 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

Flexible Input Methods: Submit documents via direct file upload, base64-encoded string, or publicly accessible URL — choose the method that best fits your architecture

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	`multipart/form-data` when using file upload, or `application/json` when using base64 or link

Request Body

Parameter	Type	Required	Description
file	file	Optional	The sample document file to be analyzed via direct upload. Supported format: PDF or Image
base64	string	Optional	Base64-encoded string of the sample image or PDF document. The string should represent a valid document.
link	string	Optional	A publicly accessible URL pointing to the sample image or PDF document. The URL must be directly downloadable and should not require authentication.
pages	string	Optional	Specific page number to process from the uploaded document.

Input Requirement

You must provide exactly one of the three input parameters — file, base64, or link. If none are provided, the request will fail.

File Requirements (applies to all input methods):

Format: Image or PDF

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
Input Method Guidelines:

file: Best suited for server-side integrations where the document is available on disk. Use multipart/form-data encoding.

base64: Ideal for mobile applications, serverless functions, or pipelines where the document is already loaded in memory. Send as a JSON payload with application/json content type.

link: Convenient when documents are hosted in cloud storage (e.g., S3, GCS, Azure Blob) or served via a CDN. Ensure the URL is publicly accessible or pre-signed. Send as a JSON payload with application/json content type.

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: When using file, the endpoint expects multipart/form-data encoding. When using base64 or link, send a JSON payload with Content-Type: application/json. The page parameter is optional in all cases.

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 the 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

The response format is identical regardless of which input method (file, base64, or link) was used

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

Base64 Validation: When using base64 input, validate that the encoded string represents a valid PDF before sending to avoid unnecessary API calls and processing errors

Link Security: When using the link input method, ensure URLs use HTTPS and are not vulnerable to SSRF (Server-Side Request Forgery) attacks. Avoid passing user-supplied URLs directly without validation

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

Pre-signed URLs: When using the link method with cloud storage, use time-limited pre-signed URLs instead of making documents permanently public

User Experience Guidelines

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

Input Method Selection: Offer users the most appropriate input method for their workflow — file upload for manual submissions, base64 for programmatic integrations, and link for cloud-hosted documents

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. When using the link input method, ensure the document URL does not inadvertently expose sensitive storage paths or internal infrastructure details.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

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