Add Attachment

Endpoint Overview

POST /api/v1/ai-playground/add-attachment

Description

The Add Attachment API allows you to enhance an existing recipe by adding a new sample document or image that helps refine the extraction schema. This endpoint processes the uploaded attachment and updates the recipe configuration to improve field detection and extraction accuracy. By providing additional document examples, the AI can better understand variations in document layouts, formats, and field positions, resulting in more robust and reliable data extraction.

This endpoint is particularly valuable when your initial recipe creation didn't capture all variations of a document type, or when you need to train the system on additional document formats. The API accepts the attachment, analyzes its content, and automatically updates the recipe's field definitions and extraction logic. The response includes the updated recipe metadata with enhanced field mappings, allowing you to validate the improvements before using the recipe in production workflows.

Key Benefits

Continuous Recipe Improvement: Enhance existing recipes with new document samples without recreating from scratch

Format Variation Handling: Train recipes to handle multiple document layouts and format variations for the same document type

Flexible File Support: Accept various file formats including images and PDFs to accommodate different document sources

Instant Schema Updates: Receive immediate feedback on updated field definitions and extraction capabilities after attachment processing

Use Cases

Education & Academic

Financial Services

Healthcare & Insurance

Add variations of student ID cards from different academic years or departments to improve recognition accuracy

Enhance transcript extraction recipes by adding samples with different GPA calculation formats or course structures

Train certificate verification recipes with samples from multiple issuing authorities with varying layouts

Improve form processing by adding examples with different handwriting styles or print formats

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
recipe_id	string	Yes	Unique identifier of the recipe to which the attachment will be added. This must be an existing recipe ID obtained from the Recipe Builder API.
file	file	Yes	The attachment file to be processed and added to the recipe. Supported formats include images (JPEG, PNG) and PDF documents. The file should represent a variation or example of the document type the recipe is designed to process.

File Requirements:

Formats: PDF, JPEG, PNG, and other common image formats

Quality: Clear, readable text and well-defined structure

Content: Should be a valid example of the document type handled by the recipe

Size: Maximum file size may vary based on your plan

Example Request

Note: This endpoint uses multipart/form-data encoding to support file uploads. The recipe_id should be provided as form data along with the file attachment.

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding the updated recipe information
data.recipe_id	string	Unique identifier of the recipe that was updated
data.keys	object	Updated field schema showing data types for each extractable field. Keys represent field names, values indicate data types (str, int, float, bool, etc.)
data.description	string	AI-generated description of the document type and its contents based on the attached file
data.model	string/null	Model configuration used for processing (null indicates default model)
data.name	string	Human-readable name assigned to the recipe schema
data.created_at	string	Date when the recipe was originally created (ISO 8601 format: YYYY-MM-DD)
data.tag	string	Category or classification tag assigned to the recipe (e.g., "general", "financial", "identity")
data.preference_type	string	Processing preference setting that affects extraction behavior (e.g., "latency" for faster processing, "accuracy" for more precise extraction)
data.pages	array	Array of page numbers for PDF documents. Empty array for image files.
data.use_pdf	boolean	Indicates whether the recipe processes PDF documents (false for image-based recipes)
data.doc_url	string/null	URL to the stored attachment document. Null if not yet processed or unavailable.
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_fxwFeY",
        "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"
}

Response Field Notes:

The keys object shows the updated field schema with inferred data types

Data type notations: "str" (string), "int" (integer), "float" (floating-point number), "bool" (boolean)

The description field provides AI-generated context about the document

An empty pages array indicates the attachment is an image file rather than a PDF

The use_pdf field helps identify the document format being processed

Possible Error Responses

Invalid Recipe ID

Invalid File Format

Missing Recipe ID

Missing File

Authentication Error

{
    "data": null,
    "status_code": 404,
    "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 belongs to a different account. Verify the recipe ID is correct and belongs to your account.

Integration Best Practices

Security Recommendations

Recipe ID Validation: Verify that users have ownership of the recipe_id before allowing attachment uploads to prevent unauthorized recipe modifications

File Sanitization: Implement virus scanning and file validation on your application layer before forwarding files to the API

Token Security: Store JWT tokens securely and never expose them in client-side code or version control systems

HTTPS Only: Always use HTTPS endpoints to encrypt file data and recipe IDs during transmission

Access Control: Implement role-based access control to restrict which users can modify recipes within your organization

Audit Logging: Maintain detailed logs of all recipe modifications including attachment additions for compliance and troubleshooting

User Experience Guidelines

Pre-upload Validation: Validate file format, size, and readability on the client side before upload to reduce errors and improve response time

Progress Indicators: Display upload progress and processing status to keep users informed during attachment processing

Recipe Comparison: Show before/after field schemas to help users understand how the attachment improved the recipe

Attachment Previews: Display thumbnails or previews of uploaded attachments for visual confirmation before submission

Version Control: Maintain a history of recipe modifications so users can track changes and rollback if needed

Batch Upload Support: Consider allowing multiple attachment uploads in sequence to train recipes on various document formats

Quality Feedback: Provide suggestions on improving attachment quality if initial processing identifies issues

Success Confirmation: Clearly indicate when attachments are successfully added and the recipe is updated

Code Samples

cURL

Python

Node.js

Related APIs

Recipe Builder API: Creates new recipes from sample documents - the source of recipe_ids used by this endpoint. Fetch Build Recipe API: Retrieves complete recipe details and schema to verify updates after adding attachments. Execute Build Recipe API: Processes documents using the enhanced recipe to extract structured data with improved accuracy. Update Build Recipe API: Modifies recipe configurations and field definitions programmatically. Delete Build Recipe API: Removes recipes that are no longer needed from your account.

Compliance and Legal Considerations

When adding attachments to recipes, ensure compliance with data protection regulations including GDPR, CCPA, and local privacy laws. Attachments should not contain real personally identifiable information (PII) unless you have explicit consent and legal basis for processing. Consider using anonymized or synthetic document samples for recipe enhancement to minimize privacy risks. The uploaded attachments may be stored for processing and quality improvement purposes - refer to Surepass's privacy policy for data retention details. Organizations in regulated industries must ensure attachments do not contain protected information covered by sector-specific regulations such as HIPAA (healthcare protected health information), GLBA (financial records), or FERPA (educational records). If using production documents as attachments, implement proper anonymization techniques and obtain necessary approvals from your data protection officer or legal team. Maintain detailed records of what types of documents are used for recipe training and ensure appropriate data processing agreements are in place. For documents containing children's information, ensure compliance with COPPA and other child protection regulations. The enhanced recipe may inherit characteristics from the attachment data, so ensure all training documents meet your organization's data quality and ethical standards.

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/add-attachment' \ --header 'Authorization: Bearer <token>' \ --form 'file=@""' \ --form 'recipe_id="rec_veh_reg_12345"'

{ "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" }

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