How to create records through the FileMaker Data API

You've got a web form, a mobile app, or another system that needs to push new records straight into FileMaker — and you're tired of exporting CSVs, running import scripts, or having someone re-key data every morning. Maybe your webshop takes an order at 2 a.m. and nobody looks at it until the FileMaker import script runs at 9. That gap is exactly what the FileMaker Data API is built to close.

This article walks through exactly how to create a record through the Data API — the request structure, the auth flow, the common mistakes, and the design decisions that separate a script that works in testing from one that survives production traffic.

What is the FileMaker Data API, in plain terms?

The Data API is a REST interface built into FileMaker Server (and Claris Server) that lets any external system — a website, a Node.js backend, an n8n or Make automation, a mobile app — talk to a FileMaker database using standard HTTP calls and JSON, instead of ODBC, XML, or a plug-in.

Instead of a nightly import script, you get a live door into your database: any app that can send a POST request can create a record the moment it happens. That's the difference between a customer's web order landing in FileMaker instantly versus sitting in a CSV folder until someone remembers to run the import.

What do you need before you can create a record?

Before writing a single line of code, confirm these four things — most "it doesn't work" support tickets trace back to one of them:

1. FileMaker Server or Claris Server is running the file, and the Data API is enabled for that specific database in the admin console (it's off by default for security reasons).
2. A FileMaker account with the right privilege set — the account needs "Access via Data API" checked, plus create/edit privileges on the target table and layout.
3. A layout built for the API, not necessarily the one users see on screen. This matters more than it sounds — see below.
4. A valid SSL certificate on the server — self-signed certs will block many HTTP clients by default, which trips up a lot of first attempts from Postman or a browser-based app.

How do you actually authenticate to the Data API?

Creating a record is a two-step dance: log in, then send the record.

Step 1 — Get a session token

POST https://yourserver.com/fmi/data/vLatest/databases/YourDatabase/sessions
Authorization: Basic base64(username:password)
Content-Type: application/json

FileMaker responds with a token, valid for 15 minutes of inactivity by default:

{
 "response": { "token": "1a2b3c4d5e6f..." },
 "messages": [ { "code": "0", "message": "OK" } ]
}

Step 2 — Use that token on every subsequent call, in the header, not the body:

Authorization: Bearer 1a2b3c4d5e6f...

A practical gotcha: that token expires after 15 minutes of no activity — not 15 minutes total. If your integration runs a batch job every hour, don't cache yesterday's token; log in fresh each run, or build in logic that catches a "401 / invalid token" response and automatically re-authenticates before retrying.

What does the actual create-record request look like?

Once you're authenticated, creating a record is one POST call:

POST https://yourserver.com/fmi/data/vLatest/databases/YourDatabase/layouts/API_Orders/records
Authorization: Bearer 1a2b3c4d5e6f...
Content-Type: application/json

{
 "fieldData": {
 "CustomerName": "Jansen Groothandel BV",
 "OrderDate": "03/14/2025",
 "OrderTotal": "1249.50",
 "Status": "New"
 }
}

A successful response returns the new record's internal ID and mod count:

{
 "response": { "recordId": "482", "modId": "0" },
 "messages": [ { "code": "0", "message": "OK" } ]
}

Hold onto that recordId — you'll need it if the same integration later needs to update or attach a file to that record.

Why should you use a dedicated layout instead of your main data-entry layout?

This is the mistake that causes the most confusing bugs later. The Data API only sees fields that exist on the layout you point it at — not the whole table.

If your order-entry layout has a calculation field, a portal, or a container field the API call doesn't expect, you can get silent failures, unexpected auto-enter behavior, or performance drag from portals loading unnecessarily. The fix: build a lean, dedicated layout — something like API_Orders — that exposes only the fields the integration actually needs to read or write. It also gives you a stable contract: your visible UI layout can be redesigned freely without ever breaking the integration, because the API isn't touching it.

How do you set related fields or create a parent-and-child record together?

A common real scenario: creating a new Order plus its Line Items in one call, instead of two round trips. The Data API supports this through portalData:

{
 "fieldData": {
 "CustomerName": "Jansen Groothandel BV",
 "OrderDate": "03/14/2025"
 },
 "portalData": {
 "LineItems": [
 { "ProductName": "Widget A", "Qty": "4", "Price": "12.50" },
 { "ProductName": "Widget B", "Qty": "1", "Price": "39.00" }
 ]
 }
}

The portal name in the JSON must exactly match the portal's object name on the layout — not the related table name. This trips up almost everyone the first time, because FileMaker's layout inspector shows the table occurrence name by default; you have to explicitly name the portal object.

How should you handle errors so the integration doesn't silently fail?

In a real production integration — say, a webshop pushing orders into FileMaker all day — things will occasionally go wrong: a required field is missing, a value fails validation, the session token expired mid-batch, or the server is mid-backup and briefly unavailable. Plan for it:

• Check the messages[0].code on every response. "0" means success; anything else is an error you need to branch on. Don't assume a 200 HTTP status means the record was created — FileMaker can return HTTP 200 with an error code in the body.
• Retry on token expiry (401/952), not on validation errors. A bad field value will fail every time you retry it; blindly retrying just wastes calls and hides a real data problem.
• Log the payload that failed, not just the error code. When a customer says "three orders never showed up," you need to see exactly what was sent, not just that something failed.
• Set a reasonable timeout and a queue. If your source system fires 50 records in one second, sending them all at once can overload a low-tier FileMaker Server. A small queue with a short delay between calls is far more reliable than a firehose.

What are common reasons record creation fails, and how do you fix each one?

Symptom	Likely cause	Fix
401 Unauthorized	Token expired or never obtained	Re-authenticate, check the account has "Access via Data API"
"Field is missing" or silent field drop	Field not on the target layout	Add the field to your dedicated API layout
500 error with cryptic message	Value fails a validation rule or calculation	Check field validation settings; test the same value manually in FileMaker
Portal data not saving	Portal object name mismatch	Rename in JSON to match the layout's portal object name exactly
Works in Postman, fails from the app	SSL certificate not trusted by the client	Install a valid CA-signed certificate on the server
Intermittent failures under load	Too many simultaneous calls	Add a request queue / throttle on the sending side

Should you build this with plain scripts, or add a framework like FMBetterForms or AI on top?

Raw Data API calls work well for straightforward integrations — one system pushing orders, leads, or tickets into FileMaker. But two situations change the calculus:

• You need a polished external-facing form. If customers or field staff will be filling in the data that eventually becomes a FileMaker record, a tool like FMBetterForms lets you build a modern, responsive web form that posts directly into FileMaker via the Data API — without asking non-technical users to touch JSON or Postman.
• You want the system to interpret unstructured input before creating the record. This is where AI is increasingly used inside FileMaker workflows: an incoming email, a scanned PO, or a free-text WhatsApp message gets parsed by an AI model, mapped to structured fields, and then written into FileMaker through the same Data API create-record call described above. The API call itself doesn't change — what changes is what generates the JSON payload.

In both cases, the underlying mechanic is identical to what's described in this article: authenticate, POST fieldData to a dedicated layout, handle the response. The complexity moves to what happens before the API call, not the call itself.

How does this fit into a broader FileMaker integration strategy?

Creating records is usually just one piece of a bigger connection between FileMaker and the rest of your software stack — you'll often also need to read records, update them, and trigger actions in the other direction. If you're building out that bigger picture, our guide on how to connect FileMaker to modern applications and services covers the full range of integration patterns beyond just record creation.

Quick checklist before you go live

• Data API enabled for the specific file in FileMaker Server admin console
• Dedicated account with "Access via Data API" and correct privilege set
• Valid, CA-signed SSL certificate installed on the server
• Dedicated, minimal API layout — not your main UI layout
• Token refresh logic in place for long-running or scheduled integrations
• Error-code checking on every response, not just HTTP status
• Logging of failed payloads for troubleshooting
• Throttling/queueing if the source system can burst many requests at once

FAQ

Can the Data API create more than one record per call? Not directly for the parent table — each call to the records endpoint creates one record. You can create related child records in the same call via portalData, and you can script a loop to send multiple calls quickly, but there's no native "bulk insert" endpoint.

Does creating a record via the Data API trigger FileMaker scripts? Only if you explicitly request it. You can pass a script parameter in the same call to run a server-side script after the record is created — useful for sending a notification, updating a related record, or kicking off further logic.

Is the Data API fast enough for high-volume integrations? For moderate volume (dozens to a few hundred records per minute) it performs well on adequately sized FileMaker Server hardware. For very high-volume, near-real-time streams, pair it with a queue on the sending side rather than firing requests as fast as possible.

Do I need FileMaker Pro installed to use the Data API? No — the Data API is a server-side feature. The sending system just needs to make standard HTTPS calls; no FileMaker client software is required on that end.

If you're weighing whether to build this integration in-house, add a front-end form on top of it, or bring AI into the mix to handle messy incoming data before it reaches FileMaker, it helps to map out the whole flow first. Loggix builds custom FileMaker solutions and API integrations exactly like this, and can also advise on where a tool like FMBetterForms or an AI parsing step genuinely saves time versus adds unnecessary complexity for your specific case.