API endpoints overview

List environments

List environments Retrieves all environments and their associated keys for your account. Secret Key values are never returned - only metadata. **What's included:** - Environment name - Key prefixes and IDs - Allowed origins for Public Keys - Last usage timestamps

Create environment

Create environment Creates a new environment with a pair of API keys (Secret Key and Public Key). Use environments to separate your development, staging, and production deployments. **What you get:** - Secret Key: For server-to-server API calls - Public Key: For client-side SDK usage with origin restrictions **Important:** Save the Secret Key immediately - it's only shown once.

Update origins

Update origins Updates the allowed origins for an environment's Public Key. This controls which domains can use the Public Key for client-side SDK integration. **Origin format:** - `https://example.com` - `https://*.example.com` (wildcard subdomains) - `http://localhost:3000` (development) **Security:** Requests from unlisted origins will be rejected.

Delete environment

Delete environment Permanently deletes an environment and revokes both its Secret Key and Public Key. This action cannot be undone. **Important:** - All API calls using these keys will immediately fail - Active SDK instances will stop working - Consider rotating keys instead if you need to maintain service

Presign upload

Presign upload Generates a presigned URL that allows direct file upload to storage. The URL is valid for 1 hour and supports files up to 500MB. **Supported file types:** - Spreadsheets: .xlsx, .xls, .csv, .tsv - Documents: .txt, .json, .pdf - Images: .png, .jpg, .jpeg, .webp **Upload flow:** 1. Call this endpoint to get a presigned URL 2. Upload your file directly to the returned URL using HTTP PUT 3. The file is automatically associated with your import

Presign download

Presign download Generates a presigned URL for downloading the original file associated with an import. The URL is valid for 5 minutes. **Use cases:** - Download the original uploaded file for review - Retrieve files for backup or archival purposes

Delete file

Delete file Permanently deletes a file and removes its reference from the import. This action cannot be undone.

List imports

List imports Retrieves a paginated list of all imports for your account. Results are ordered by creation date (newest first by default). **Pagination:** - Use `limit` to control page size (1-100, default 20) - Use `cursor` from the previous response to fetch the next page - Use `direction` to sort ascending or descending **Filtering:** - Filter by `templateId` to get imports for a specific template

Create import

Create import Creates a new import record with the validated data from your end-users. This endpoint stores the imported rows and associates them with a template. **What gets stored:** - Import metadata (template, file reference, timestamps) - All validated rows and cells - End-user information for compliance (if provided via session) **Template resolution:** - If `schema.id` is provided, the template is looked up by ID - If not found or no ID provided, template is looked up by `schema.key` - If no template exists, a new one is automatically created

Get import details

Get import details Retrieves detailed information about a specific import including: - Import metadata and timestamps - File information (if attached) - Cell statistics and field breakdown - Compliance data (user info, IP, origin)

Delete import

Delete import Deletes a specific import by ID along with all its associated data. This action cannot be undone. **What gets deleted:** - The import record - All cells (row data) for this import - The associated file (if any)

Get import rows

Get import rows Retrieves all data rows for a specific import. Returns the actual cell values organized by row. **Note:** For large imports (10k+ rows), consider using the export endpoint instead.

Delete imports by user ID

Delete imports by user ID Deletes all imports and associated data for a specific end-user identified by their user ID. This endpoint is designed for GDPR/CCPA compliance when users request data deletion. **What gets deleted:** - All import records for the specified user - All cells (row data) associated with those imports - All files uploaded by the user

Delete imports by email

Delete imports by email Deletes all imports and associated data for a specific end-user identified by their email. This endpoint is designed for GDPR/CCPA compliance when users request data deletion. **What gets deleted:** - All import records for the specified user - All cells (row data) associated with those imports - All files uploaded by the user

Map headers

Map headers Uses AI to intelligently map imported file headers to your template's schema headers. This helps automatically match column names even when they don't exactly match. **How it works:** - Provide your schema headers (expected columns) and file headers (actual columns from import) - AI analyzes semantic similarity and common variations - Returns a mapping of schema keys to file keys **Example use case:** Your schema expects "First Name" but the file has "FirstName" or "Given Name" - AI maps them correctly.

Predict field types

Predict field types Uses AI to intelligently predict the most appropriate field type for each header in a schema-less import. This helps users quickly configure their data import by suggesting field types based on header names. **How it works:** - Provide an array of headers from the imported file - AI analyzes each header name to determine the most likely data type - Returns a mapping of header keys to predicted field types **Example predictions:** - "Cost", "Price", "Amount" → monetary - "Phone", "Telephone", "Mobile" → phone - "Active", "Enabled", "Is Valid" → checkbox - "Birth Date", "Created At" → date - Ambiguous headers → text (safe default) **Note:** This endpoint never fails. If AI prediction fails or returns invalid data, all headers default to "text".

Create session

Create session Creates a temporary session token that allows your end-users to import data through the SDK. Sessions are time-limited and tied to specific end-user identifiers for compliance. **Authentication:** - Requires Secret Key (server-to-server only) **Session flow:** 1. Your backend calls this endpoint with end-user information 2. You receive a session token 3. Pass the token to your frontend SDK 4. End-user can now import data using that token **Expiration:** - Default: 1 hour - Maximum: 24 hours - Specify custom duration with `expiresIn` (in seconds) **End-user identification:** - `endUserId` is required for tracking and compliance - `endUserEmail` is optional but recommended - These identifiers are used for GDPR/CCPA data deletion requests

Get overview

Get overview Returns summary statistics for your account including total counts and recent activity. **What's included:** - Total number of templates - Total number of imports - 5 most recent imports with metadata **Use cases:** - Display usage stats in your dashboard - Monitor import activity - Track template usage

List templates

List templates Retrieves all templates for your account, ordered by creation date (newest first). **Use cases:** - Display available templates in your UI - Select a template for a new import - Manage your template library

Create template

Create template Creates a new template with a schema that defines the structure and validation rules for data imports. **What is a template:** - Defines the expected columns (fields) for your imports - Specifies validation rules for each field - Configures data transformations - Can be reused across multiple imports

Get template

Get template Retrieves a specific template by ID including its full schema definition. **Use cases:** - Load template configuration for an import - Display template details - Edit template settings

Delete template

Delete template Permanently deletes a template. This action cannot be undone. **Important:** - Existing imports using this template are not affected - Future imports cannot use this template - Template ID cannot be reused

Update template

Update template Updates an existing template's schema or configuration. Only the provided fields will be updated. **What can be updated:** - Schema definition (fields, validation rules) - Template key - Any schema configuration **Note:** Updating a template affects all future imports using this template. Existing imports are not affected.