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. You can provide the document via file upload, base64-encoded string, or a publicly accessible URL. 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 Input Options: Submit documents via file upload, base64-encoded string, or publicly accessible URL to accommodate different integration architectures
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
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
No
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.
base64
string
No
Base64-encoded string of the document to be processed and added to the recipe. This should be the complete base64 representation of a supported file format (PDF, JPEG, PNG). Useful for integrations where files are already encoded in memory or received from other systems.
link
string
No
Publicly accessible URL pointing to the document to be processed and added to the recipe. The URL must directly link to a supported file format (PDF, JPEG, PNG) and be accessible without authentication. Useful for documents already hosted on cloud storage or content delivery networks.
Input Requirement
While file, base64, and link are each individually optional, at least one of these three parameters must be provided in every request.
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
Base64 Requirements:
Must be a valid base64-encoded string of a supported file format
Should not include the data URI prefix (e.g., do not include data:image/png;base64,)
Ensure encoding is complete and not truncated
Link Requirements:
Must be a publicly accessible URL (no authentication required to access)
URL must point directly to a supported file format (PDF, JPEG, PNG)
Temporary or pre-signed URLs (e.g., AWS S3 pre-signed URLs) are supported as long as they are valid at the time of the request
HTTPS URLs are recommended for secure transmission
Note: When using file upload, this endpoint requires multipart/form-data encoding. When using base64 or link, use application/json encoding. The recipe_id is required in all cases.
{"data":null,"status_code":400,"success":false,"message":"One of file, base64, or link is required","message_code":"missing_document_input"}
This error occurs when none of the three document input parameters (file, base64, or link) are provided. Include at least one document input method in the request.
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
Base64 Validation: Validate base64 strings for proper encoding and expected file signatures before submitting to avoid processing errors
Link Security: Only allow URLs from trusted domains and validate that links point to expected file types before submission
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
Input Method Selection: Provide a clear interface allowing users to choose between file upload, base64 input, or URL submission based on their workflow
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
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. When using the link parameter, ensure the document URL does not expose sensitive information through URL parameters and that the hosting location complies with your data residency requirements.
Request
Authorization
Provide your bearer token in the
Authorization
header when making requests to protected resources.
