Docs

1. Install

Filio ships as a React component. Install via npm:

npm install @usefilio/react

Vue, Angular, and vanilla JS adapters are on the roadmap. Email if you need one and we'll prioritize.

2. Get your API key

From your dashboard at app.usefilio.com, go to API Keysand create a new key. Copy it somewhere safe - you'll need it in the next step.

The API key authenticates your importer with Filio's backend. Treat it like any other API credential.

3. Create a template

Templates define the shape of data your users will import. Each template has a list of fields, and each field has a type and validation rules.

From your dashboard, go to Templates -> New template. For each field, set:

• Name - the key in the JSON output (e.g. first_name)
• Display name- what users see in the importer (e.g. "First name")
• Type - text, email, phone, number, date, URL, or enum
• Validation rules - required, min/max length, regex, enum values, etc.
• Required - whether the field must be mapped before import succeeds

After saving, copy the template ID from the top of the template page. It's a UUID like a1b2c3d4-e5f6-....

4. Mount the importer

Drop <FilioImporter /> wherever you want the import flow to open:

import { FilioImporter } from '@usefilio/react'

export default function ImportButton() {
  return (
    <FilioImporter
      templateId="a1b2c3d4-e5f6-..."
      apiKey="your-api-key"
      onComplete={(rows) => {
        console.log('Imported:', rows)
        // Send rows to your backend
      }}
    />
  )
}

That's it. Your users can now click the button, upload their file, and you'll get clean validated data in your onComplete callback.

5. What you get back

The onCompletecallback receives an array of row objects. Each object has your template's field names as keys, already validated and type-cast:

[
  {
    first_name: "Sarah",
    last_name: "Chen",
    email: "sarah@example.com",
    phone: "+14155552671",
    state: "California"
  },
  {
    first_name: "Marcus",
    last_name: "Webb",
    email: "marcus@example.com",
    phone: "+14155553820",
    state: "Texas"
  }
]

Numbers come back as numbers. Dates as ISO strings. Phone numbers in E.164 format. No string-parsing cleanup needed on your end.

6. Component props

The full prop list for <FilioImporter />:

^* Required props.

7. Webhooks (optional)

If you'd rather process imports on your backend instead of in the browser, configure a webhook URL in your template settings. Filio POSTs the validated rows to your endpoint after each successful import.

Webhook payload:

{
  "import_id": "imp_abc123",
  "template_id": "a1b2c3d4-...",
  "row_count": 247,
  "imported_at": "2026-04-25T14:32:00Z",
  "rows": [
    { "first_name": "Sarah", ... },
    ...
  ]
}

Webhooks include a signature header you can verify with your webhook secret. Custom validation webhooks (where Filio calls your endpoint during the import flow to validate rows server-side) are available on Starter and above.