Fetch Build Recipe

Endpoint Overview

GET /api/v1/ai-playground/fetch-build-recipe

Description

The Fetch Build Recipe API retrieves a structured schema definition for document processing recipes created in the AI Playground. This endpoint returns comprehensive metadata about document extraction templates, including field definitions, data types, page mappings, and processing status. It enables developers to programmatically access and understand the structure of custom document parsing recipes that have been configured to extract specific information from documents like ID cards, certificates, invoices, and other structured forms.

The API provides complete visibility into the recipe configuration, including the original document URL, extracted field schemas with descriptions, page-level key mappings, and processing status, making it essential for automated document processing workflows and validation pipelines.

Key Benefits

Instant Schema Retrieval: Access complete recipe configurations with a single API call using the recipe ID

Structured Field Definitions: Get detailed type information and descriptions for all extractable fields in the document

Page-Level Mapping: Understand which fields are extracted from specific pages in multi-page documents

Processing Status Tracking: Monitor recipe completion status and validate readiness for production use

Use Cases

Education Technology

Financial Services

Healthcare & Insurance

Retrieve student ID card schemas for automated enrollment systems

Process bulk student records with consistent field extraction

Validate identity documents during online admission processes

Generate standardized data models for student information systems

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 `application/json`

Query Parameters

Parameter	Type	Required	Description
recipe_id	string	Yes	Unique identifier for the build recipe. Example: `recipe_fxwFeYqwpVzju`

Example Request

Note: This is a GET request with no request body required. The recipe_id is passed as a query parameter in the URL.

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding the complete recipe information
data.doc_url	string	Presigned S3 URL to access the original document used for recipe creation
data.recipe_id	string	Unique identifier for the recipe
data.keys	object	Schema definition containing all extractable fields with their metadata
data.keys.{field_name}.type	string	Data type of the field (e.g., "string", "number", "date")
data.keys.{field_name}.description	string	Human-readable description of what the field contains
data.description	string	Overall description of the document type and recipe purpose
data.name	string	Friendly name assigned to the recipe schema
data.pages	array	List of page numbers included in the document (e.g., [1] for single-page documents)
data.use_pdf	boolean	Indicates whether the source document is in PDF format
data.status	string	Processing status of the recipe (e.g., "completed", "processing", "failed")
data.keys_mappings	array	Array of objects mapping fields to specific document pages
data.keys_mappings[].page_no	integer	Page number where the fields are located
data.keys_mappings[].keys	array	List of field names extracted from this page
status_code	integer	HTTP status code (200 for success)
success	boolean	Indicates if the request was successful
message	string	Human-readable message describing the result
message_code	string	Machine-readable code for the result status

Example Successful Response

{
    "data": {
        "doc_url": "https://playground-docs.s3.amazonaws.com/recipe_builder_mhCDemlkeH/ai_playground/recipe_builder_17656404.pdf",
        "recipe_id": "recipe_builder_mhCDem",
        "keys": {
            "school_name": {
                "type": "string",
                "description": "Name of the school or institution."
            },
            "school_address": {
                "type": "string",
                "description": "Address of the school or institution."
            },
            "card_type": {
                "type": "string",
                "description": "Type of the ID card, e.g., 'Student ID Card'."
            },
            "student_name_label": {
                "type": "string",
                "description": "Label indicating the student's name."
            },
            "student_name": {
                "type": "string",
                "description": "Full name of the student."
            },
            "member_id_label": {
                "type": "string",
                "description": "Label indicating the member ID."
            },
            "member_id": {
                "type": "string",
                "description": "Unique identification number assigned to the student."
            },
            "phone_label": {
                "type": "string",
                "description": "Label indicating the phone number."
            },
            "phone_number": {
                "type": "string",
                "description": "Phone number of the student."
            },
            "address_label": {
                "type": "string",
                "description": "Label indicating the address."
            },
            "student_address": {
                "type": "string",
                "description": "Address of the student."
            }
        },
        "description": "A student identification card with personal and school information.",
        "name": "Student ID Card Schema",
        "pages": [
            1
        ],
        "use_pdf": true,
        "status": "completed",
        "keys_mappings": [
            {
                "page_no": 1,
                "keys": [
                    "school_name",
                    "school_address",
                    "card_type",
                    "student_name_label",
                    "student_name",
                    "member_id_label",
                    "member_id",
                    "phone_label",
                    "phone_number",
                    "address_label",
                    "student_address"
                ]
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Recipe ID

Authentication Error

Missing Recipe ID

{
    "data": null,
    "status_code": 400,
    "success": false,
    "message": "Recipe not found",
    "message_code": "recipe_not_found"
}

This error occurs when the provided recipe_id does not exist in the system or has been deleted.

Integration Best Practices

Security Recommendations

Secure Token Storage: Store JWT tokens securely using environment variables or secure credential management systems, never hardcode them in source code

Token Rotation: Implement automatic token refresh mechanisms before expiration to maintain uninterrupted service

HTTPS Only: Always use HTTPS endpoints to encrypt data in transit and protect sensitive recipe information

Access Control: Restrict recipe_id access to authorized users only and implement role-based access control in your application

Rate Limiting: Implement client-side rate limiting to avoid overwhelming the API and triggering security blocks

User Experience Guidelines

Caching Strategy: Cache recipe schemas locally to reduce API calls and improve response times for frequently accessed recipes

Loading States: Display loading indicators while fetching recipe data to inform users of ongoing operations

Error Handling: Provide user-friendly error messages when recipes cannot be fetched, guiding users on next steps

Progressive Enhancement: Load and display recipe metadata incrementally, showing basic information first while detailed schemas load

Status Awareness: Check the recipe status field and inform users if a recipe is still processing or has failed

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

When using this API to access document processing recipes, ensure compliance with data protection regulations such as GDPR, CCPA, and local privacy laws. The doc_url field contains presigned URLs that expire after a set period for security purposes. Do not store or share these URLs beyond their expiration time. If processing personally identifiable information (PII) such as student IDs, phone numbers, or addresses, implement appropriate data protection measures including encryption at rest, access logging, and data retention policies. Ensure you have proper consent and legal basis for processing personal data extracted using these recipes. Organizations in regulated industries (education, finance, healthcare) must verify that their use of this API complies with sector-specific regulations such as FERPA, GLBA, or HIPAA as applicable.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": { "doc_url": "https://playground-docs.s3.amazonaws.com/recipe_builder_mhCDemlkeH/ai_playground/recipe_builder_17656404.pdf", "recipe_id": "recipe_builder_mhCDem", "keys": { "school_name": { "type": "string", "description": "Name of the school or institution." }, "school_address": { "type": "string", "description": "Address of the school or institution." }, "card_type": { "type": "string", "description": "Type of the ID card, e.g., 'Student ID Card'." }, "student_name_label": { "type": "string", "description": "Label indicating the student's name." }, "student_name": { "type": "string", "description": "Full name of the student." }, "member_id_label": { "type": "string", "description": "Label indicating the member ID." }, "member_id": { "type": "string", "description": "Unique identification number assigned to the student." }, "phone_label": { "type": "string", "description": "Label indicating the phone number." }, "phone_number": { "type": "string", "description": "Phone number of the student." }, "address_label": { "type": "string", "description": "Label indicating the address." }, "student_address": { "type": "string", "description": "Address of the student." } }, "description": "A student identification card with personal and school information.", "name": "Student ID Card Schema", "pages": [ 1 ], "use_pdf": true, "status": "completed", "keys_mappings": [ { "page_no": 1, "keys": [ "school_name", "school_address", "card_type", "student_name_label", "student_name", "member_id_label", "member_id", "phone_label", "phone_number", "address_label", "student_address" ] } ] }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Description#

Use Cases#

Technical Implementation#

Request Headers#

Query Parameters#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses