Fetch Execute Recipe

Endpoint Overview

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

Description

The Fetch Executed Recipe API retrieves the results of a previously executed document processing operation. After submitting a document for processing using a recipe, this endpoint allows you to check the extraction status and retrieve the structured data that was extracted from the document. The API returns both the processing status and the complete extracted data mapped to the fields defined in the recipe schema.

This endpoint is essential for asynchronous document processing workflows, where documents are submitted for processing and results are retrieved separately. It enables tracking of processing completion, handling of long-running operations, and retrieval of extracted data once processing is complete. The client_id acts as a unique identifier for each execution instance, allowing multiple documents to be processed simultaneously while maintaining traceability.

Key Benefits

Asynchronous Processing Support: Check status and retrieve results independently from document submission, enabling non-blocking workflows

Structured Data Extraction: Receive extracted information as key-value pairs matching your recipe schema for easy integration

Execution Tracking: Monitor processing status (completed, processing, failed) to handle long-running document extractions

Multi-Document Management: Use unique client_ids to manage and retrieve results from multiple concurrent document processing operations

Use Cases

Education & Training

Financial Services

Healthcare & Insurance

Retrieve extracted student information from processed ID cards for enrollment systems

Fetch transcript data after bulk document processing for academic records management

Monitor completion status of certificate verification batches during admission cycles

Extract and retrieve student demographics from application forms for reporting and analytics

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
client_id	string	Yes	Unique identifier for the recipe execution instance. This is returned when a document is submitted for processing. Example: `recipe_executor_clOSPz`

Example Request

Note: This is a GET request with no request body required. The client_id is passed as a query parameter in the URL to identify the specific execution instance.

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding the execution results and metadata
data.recipe_id	string	Identifier of the recipe used for document processing
data.client_id	string	Unique identifier for this execution instance, matching the requested client_id
data.response	object	Extracted data from the document as key-value pairs matching the recipe schema
data.response.{field_name}	string/number/boolean	Extracted values for each field defined in the recipe. Field names and types vary based on the recipe schema
data.status	string	Current processing status. Possible values: "completed", "processing", "failed"
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": {
        "recipe_id": "recipe_KvUqRpa",
        "client_id": "recipe_executor_clOSPz",
        "response": {
            "academy_name": "INGOUDE ACADEMY",
            "academy_address": "123 Anywhere St., Any City, ST 12345",
            "card_type": "Student ID Card",
            "photo": "null",
            "name": "Daniel Gallego",
            "member_id": "123-456-7890",
            "phone": "+123-456-7890",
            "address": "123 Anywhere St., Any City, ST 12345"
        },
        "status": "completed"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Response Field Notes:

The response object contains dynamic fields based on the recipe schema used for processing

Field names in the response object correspond to the keys defined in the recipe

Fields may contain "null" as a string value when data could not be extracted from the document

All extracted values are returned as strings by default, even for numeric data

Possible Error Responses

Invalid Client ID

Authentication Error

{
    "data": null,
    "status_code": 404,
    "success": false,
    "message": "Execution not found",
    "message_code": "execution_not_found"
}

This error occurs when the provided client_id does not exist in the system, has expired, or belongs to a different account.

Integration Best Practices

Security Recommendations

Secure Client ID Management: Store client_ids securely and never expose them in client-side code or public repositories

Token Security: Implement automatic JWT token refresh mechanisms before expiration to ensure uninterrupted access

HTTPS Only: Always use HTTPS endpoints to encrypt extracted data in transit, especially when handling sensitive personal information

Access Control: Restrict client_id access to authorized users and implement proper authentication on your application layer

Data Cleanup: Implement a process to securely delete extracted data once it has been consumed and stored in your systems

User Experience Guidelines

Polling Strategy: Implement exponential backoff polling (start with 2s, increase to 5s, 10s) to check processing status without overwhelming the API

Status Indicators: Display clear visual feedback for different statuses (processing, completed, failed) to keep users informed

Timeout Handling: Set reasonable timeout limits and notify users if processing takes longer than expected

Partial Data Display: Show extracted fields progressively as they become available for better perceived performance

Error Recovery: Provide users with clear guidance and retry options when processing fails, including document quality tips

Webhook Alternative: Consider implementing webhooks for real-time notifications instead of continuous polling for better efficiency

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

When retrieving extracted document data through this API, ensure compliance with applicable data protection regulations including GDPR, CCPA, and local privacy laws. The response object may contain personally identifiable information (PII) such as names, addresses, phone numbers, and identification numbers. Implement appropriate data handling measures including encryption in transit and at rest, access logging, and audit trails. Establish clear data retention policies and automatically purge extracted data after the necessary retention period. If processing data from minors (such as student information), ensure compliance with COPPA, FERPA, and other child protection regulations. Organizations must have proper legal basis and consent for processing personal data extracted from documents. Implement role-based access control to restrict who can retrieve execution results containing sensitive information. For healthcare applications, ensure HIPAA compliance when handling protected health information (PHI). For financial services, comply with GLBA and PCI-DSS requirements when processing financial documents.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": { "recipe_id": "recipe_KvUqRpa", "client_id": "recipe_executor_clOSPz", "response": { "academy_name": "INGOUDE ACADEMY", "academy_address": "123 Anywhere St., Any City, ST 12345", "card_type": "Student ID Card", "photo": "null", "name": "Daniel Gallego", "member_id": "123-456-7890", "phone": "+123-456-7890", "address": "123 Anywhere St., Any City, ST 12345" }, "status": "completed" }, "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