REST API

REST API memungkinkan server Anda membaca formulir dan kiriman, memindahkan kiriman ke dan dari spam, serta menghapusnya. API ini berupa JSON lewat HTTPS di https://ikiform.com/api/v1. Dokumen OpenAPI 3.1 ada di /api/v1/openapi.json.

Kunci API

Buat key di dashboard pada API keys. Satu key milik satu workspace dan hanya bisa melihat workspace itu. Key lengkap hanya ditampilkan sekali; Ikiform hanya menyimpan hash-nya.

Scope

Autentikasi

Kirim secret key sebagai Bearer token. API ini hanya untuk server ke server: tidak mengirim header CORS dan menjawab preflight browser dengan 405, jadi secret key tidak pernah bisa dipakai dari halaman web.

curl https://ikiform.com/api/v1/forms \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

• Key yang tidak ada, salah format, tidak dikenal, dicabut, atau kedaluwarsa mendapat 401 unauthorized dengan WWW-Authenticate: Bearer.
• Publishable key mendapat 403 forbidden (Publishable keys can only submit forms.). Key tanpa scope yang dibutuhkan mendapat 403 forbidden dengan nama scope disebut di pesannya.
• Respons dikirim dengan Cache-Control: no-store.

Contoh SDK di bawah memakai satu client yang sama:

import { createClient } from "@ikiform/sdk";

const ikiform = createClient({ apiKey: process.env.IKIFORM_SECRET_KEY! });

Penyusun request

curl "https://ikiform.com/api/v1/submissions?form_id=frm_xxxxxxxxxxxxxxxx&status=received&limit=50" \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Endpoint

Daftar formulir

GET /forms dengan scope forms:read.

• Terbaru lebih dulu. Menerima limit (1 sampai 100, default 25) dan cursor.

curl "https://ikiform.com/api/v1/forms?limit=10" \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Ambil satu formulir

GET /forms/:formId dengan scope forms:read.

• ID formulir dari workspace lain mengembalikan 404, persis seperti ID yang tidak ada.

curl https://ikiform.com/api/v1/forms/frm_xxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Daftar kiriman

GET /submissions dengan scope submissions:read.

• Terbaru lebih dulu. form_id dari workspace lain mengembalikan daftar kosong alih-alih error, jadi ID tidak bisa ditebak-tebak.

curl "https://ikiform.com/api/v1/submissions?form_id=frm_xxxxxxxxxxxxxxxx&status=received&limit=50" \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Ambil satu kiriman

GET /submissions/:id dengan scope submissions:read.

• ID dari workspace lain mengembalikan 404, persis seperti ID yang tidak ada.

curl https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3 \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Tandai sebagai spam

POST /submissions/:id/spam dengan scope submissions:write.

• Memindahkan kiriman yang diterima ke spam, mengurangi submission_count formulir, dan membatalkan pengiriman webhook-nya yang tertunda.
• Memanggilnya pada kiriman yang sudah spam mengembalikannya tanpa perubahan.

curl -X POST https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3/spam \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Tandai sebagai bukan spam

POST /submissions/:id/not-spam dengan scope submissions:write.

• Memindahkannya kembali ke diterima, menghapus skor dan alasan spam-nya, dan mengirim submission.created ke setiap endpoint webhook yang cocok.
• Memanggilnya pada kiriman yang diterima mengembalikannya tanpa perubahan.

curl -X POST https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3/not-spam \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Hapus kiriman

DELETE /submissions/:id dengan scope submissions:write.

• Menghapus kiriman dan pengiriman webhook-nya secara permanen. Tidak bisa dibatalkan. Menghapus lagi mengembalikan 404.

curl -X DELETE https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3 \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Objek

Objek berupa JSON snake_case dengan field object. Timestamp dalam ISO 8601 UTC dengan milidetik. ID kiriman berurutan menurut waktu (sub_ ditambah 26 karakter); ID formulir acak (frm_ ditambah 16 karakter).

Paginasi

Daftar diurutkan dari yang terbaru dan memakai cursor opaque.

1. Kirim request tanpa cursor.
2. Jika has_more bernilai true, kirim next_cursor sebagai cursor dengan filter yang sama.
3. Berhenti saat next_cursor bernilai null.

Halaman tetap stabil saat kiriman baru masuk: kiriman baru muncul di halaman pertama, tidak pernah sebagai duplikat di halaman berikutnya. Jangan membuat atau mengurai cursor sendiri; cursor yang tidak valid mengembalikan 400 invalid_request.

for await (const submission of ikiform.submissions.iterate({ formId: "frm_xxxxxxxxxxxxxxxx" })) {
  console.log(submission.id, submission.fields);
}

Error

Error memakai envelope yang sama dengan kiriman formulir. Setiap respons punya header X-Request-Id, yang diulang oleh error sebagai request_id.

{
  "ok": false,
  "error": { "code": "forbidden", "message": "This API key is missing the forms:read scope." },
  "request_id": "req_01k7v2c9t3e8m5q4x6z0a1b2c3"
}

Rate limit

Setiap key bisa membuat 100 request per 60 detik. Jika melewati batas, API mengembalikan 429 rate_limited dengan header Retry-After dalam detik. SDK mengeksposnya sebagai error.retryAfter.