What you can do

API v1 covers four modules, read and write:

People: directory with filters, create, edit and delete (to the trash), families and their members, church catalogs.
Groups: groups, members and leaders, networks, meetings and attendance.
Finance: treasuries, categories, transactions (record, edit, void), period summary and budgets.
Services: service dates (also recurring), service order, volunteers, songs and ministries.

Every operation, with its fields and responses, is in the API reference. You can download the OpenAPI document from there to generate clients or import it into Postman.

Create an API key

In AdminFiel, open your account menu → Developers → Create API key. Pick a template («People — read», «Finance — record transactions»…) or choose privileges one by one.

Privileges: the same permissions as AdminFiel's permission matrix (for example, view people or record transactions), with their scope.
Never more than you: a key can never do more than the person who created it. If that person loses a permission, so does the key.
Read-only, expiration and allowed IPs are optional and recommended.

The key is shown only once. Keep it in a password manager or your system's environment variables, never in a web page's code. If it leaks, revoke it and create another (or rotate it: the old one keeps working for 24 hours so you can switch without downtime).

Your first request

Send the key in the Authorization header. The church comes from the key; nothing else is needed.

curl https://api.adminfiel.com/v1/me \
  -H "Authorization: Bearer af_live_YOUR_KEY"

GET /me returns your church, the key's effective privileges and how much of the daily limit you have used. It's the best way to check your setup.

curl "https://api.adminfiel.com/v1/people?search=maria&per_page=10" \
  -H "Authorization: Bearer af_live_YOUR_KEY"

Lists, filters and pagination

Lists return data (the records), meta (current page, total) and links (next and previous). Use per_page (up to 100) and page.

To sync, ask only for what changed with updated_since (ISO 8601 date). Dates use YYYY-MM-DD; amounts are decimal strings ("150.00") with their currency, so no cents are lost.

Writing without duplicates

When you create or change something, send an Idempotency-Key header with a unique value per operation (for example, a UUID). If the connection drops and you retry with the same key, AdminFiel returns the original response instead of recording it twice. It is required for finance.

curl -X POST https://api.adminfiel.com/v1/transactions \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Idempotency-Key: 6f1c2a0e-sunday-offering" \
  -H "Content-Type: application/json" \
  -d '{"treasury_id": 12, "offering": true, "date": "2026-10-18",
       "amount": "1250.00", "description": "Sunday offering"}'

The rules are the same as in the app: a closed period can't be changed, transactions are never deleted (they are voided), your plan's people limit applies and notifications go out just as if you had done it in AdminFiel.

Errors

All errors have the same shape: {"error": {"code": "…", "message": "…"}}.

401 — key missing, invalid, revoked, expired or suspended.
402 — your plan doesn't include that module, or you reached a plan limit.
403 — the key lacks the privilege (insufficient_scope, says which) or is read-only.
404 — doesn't exist or is outside the key's scope.
409 — conflict (for example, the person is already in the group).
422 — invalid data; fields says which.
423 — that treasury's period is closed.
429 — too many requests; wait what Retry-After says.

Limits

Each plan has a number of active keys and a request limit per minute (per key) and per day (per church). The X-RateLimit-Limit and X-RateLimit-Remaining headers tell you what's left. If your integration needs more, write to soporte@adminfiel.com.

AI assistants (MCP)

AdminFiel has an MCP (Model Context Protocol) server so assistants like Claude, ChatGPT or Cursor can query your church's data with your API key. Available from the Básico plan.

Address: https://api.adminfiel.com/mcp, with the header Authorization: Bearer af_live_YOUR_KEY. AdminFiel → Developers → MCP has copy-ready setup for each client.

The assistant only sees the tools your key allows: with a «People — read» key it can search people but not see finance. It also includes ready-made reports: weekly pastoral summary, people without follow-up, prepare Sunday's service, monthly finance, campaign progress and board report.

What the assistant reads is sent to the AI provider you choose: review its privacy terms.

Webhooks

Get notified in your system when something happens in AdminFiel: new person, donation received, transaction recorded, group attendance, request resolved, volunteer assigned and more. Set them up in AdminFiel → Developers → Webhooks, or subscribe through the API with POST /webhooks (that's how Zapier, Make and n8n do it).

Each notification is a JSON POST {"id", "type", "created_at", "church_id", "data"} signed with the header X-AdminFiel-Signature: t=…,v1=…. To verify it compute HMAC-SHA256(secret, t + "." + body) and compare it with v1; reject notifications whose t is older than 5 minutes.

// Node.js
const [t, v1] = header.split(',').map(p => p.split('=')[1]);
const ok = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex') === v1;

Reply with a 2xx code within 10 seconds. If it fails we retry for about two days (1 min, 5 min, 30 min, 2 h, 12 h and 24 h). A webhook that hasn't responded for 3 days is disabled and the owner is notified. Use id to avoid processing the same notification twice.

Privacy

Your church's information includes personal data and, in many countries, sensitive data such as religious affiliation. Your church is responsible for who gets a key: share it only with trusted systems, give it the least privileges it needs, and revoke it when it's no longer used. Every key has a usage log in AdminFiel.

Versions and changes

v1 won't break: we may add fields and operations, but never remove or rename them. An incompatible change would be v2, announced well in advance. Ignore fields you don't know.

October 2026 — v1 launch: people, groups, finance and services (read and write), scoped API keys, idempotency; calendar, donations and requests (read); MCP server and signed webhooks.

The AdminFiel API