API REST

L'API REST permet à votre serveur de lire les formulaires et les soumissions, de déplacer les soumissions vers ou hors du spam, et de les supprimer. C'est du JSON en HTTPS à l'adresse https://ikiform.com/api/v1. Le document OpenAPI 3.1 se trouve à /api/v1/openapi.json.

Clés API

Créez des clés dans le tableau de bord sous API keys. Une clé appartient à un seul espace de travail et ne voit que celui-ci. La clé complète n'est affichée qu'une fois ; Ikiform n'en stocke que le hachage.

Portées

Authentification

Envoyez la clé secrète comme token Bearer. L'API fonctionne uniquement de serveur à serveur : elle n'envoie aucun en-tête CORS et répond aux preflights des navigateurs avec 405, donc une clé secrète ne peut jamais fonctionner depuis une page web.

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

• Une clé absente, mal formée, inconnue, révoquée ou expirée reçoit 401 unauthorized avec WWW-Authenticate: Bearer.
• Une clé publiable reçoit 403 forbidden (Publishable keys can only submit forms.). Une clé sans la portée nécessaire reçoit 403 forbidden avec le nom de la portée dans le message.
• Les réponses sont envoyées avec Cache-Control: no-store.

Les exemples SDK ci-dessous partagent un même client :

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

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

Compositeur de requête

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

Endpoints

Lister les formulaires

GET /forms avec la portée forms:read.

• Les plus récents en premier. Accepte limit (1 à 100, 25 par défaut) et cursor.

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

Récupérer un formulaire

GET /forms/:formId avec la portée forms:read.

• Un id de formulaire d'un autre espace de travail renvoie 404, exactement comme un id qui n'existe pas.

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

Lister les soumissions

GET /submissions avec la portée submissions:read.

• Les plus récentes en premier. Un form_id d'un autre espace de travail renvoie une liste vide plutôt qu'une erreur, pour que les ids ne puissent pas être sondés.

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

Récupérer une soumission

GET /submissions/:id avec la portée submissions:read.

• Les ids d'un autre espace de travail renvoient 404, exactement comme des ids qui n'existent pas.

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

Marquer comme spam

POST /submissions/:id/spam avec la portée submissions:write.

• Déplace une soumission reçue vers le spam, diminue le submission_count du formulaire et annule ses livraisons de webhook en attente.
• L'appeler sur une soumission déjà marquée comme spam la renvoie inchangée.

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

Marquer comme légitime

POST /submissions/:id/not-spam avec la portée submissions:write.

• La replace parmi les reçues, efface son score et ses raisons de spam, et envoie submission.created à chaque endpoint de webhook concerné.
• L'appeler sur une soumission reçue la renvoie inchangée.

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

Supprimer une soumission

DELETE /submissions/:id avec la portée submissions:write.

• Supprime définitivement la soumission et ses livraisons de webhook. Impossible d'annuler. Une nouvelle suppression renvoie 404.

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

Objets

Les objets sont du JSON en snake_case avec un champ object. Les horodatages sont en ISO 8601 UTC avec les millisecondes. Les ids de soumission sont triés par date (sub_ suivi de 26 caractères) ; les ids de formulaire sont aléatoires (frm_ suivi de 16 caractères).

Pagination

Les listes commencent par les plus récents et utilisent des curseurs opaques.

1. Faites une requête sans curseur.
2. Si has_more vaut true, envoyez next_cursor dans cursor avec les mêmes filtres.
3. Arrêtez quand next_cursor vaut null.

Les pages restent stables pendant l'arrivée de nouvelles soumissions : les nouvelles apparaissent sur la première page, jamais en double plus loin. Ne construisez pas et n'analysez pas les curseurs vous-même ; un curseur invalide renvoie 400 invalid_request.

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

Erreurs

Les erreurs utilisent la même enveloppe que les soumissions de formulaire. Chaque réponse a un en-tête X-Request-Id, que les erreurs reprennent en request_id.

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

Limite de débit

Chaque clé peut faire 100 requêtes par tranche de 60 secondes. Au-delà, l'API renvoie 429 rate_limited avec un en-tête Retry-After en secondes. Le SDK l'expose dans error.retryAfter.