Submit a Form - Raykoi

curl -X POST "https://api.raykoi.com/api/v1/submit/p/YOUR_PUBLIC_ID" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"data": {"email": "user@example.com", "name": "Alice"}}'

import { createClient } from '@raykoi/sdk';

const client = createClient();
await client.form('YOUR_PUBLIC_ID').submit({
  email: 'user@example.com',
  name: 'Alice',
});

{
  "success": true,
  "submission_id": "sub_pub_1a2b3c",
  "submission_number": 42
}

{
  "error": "Validation failed",
  "errors": [
    { "field": "email", "fieldId": "email", "message": "Enter a valid email address", "type": "pattern" }
  ]
}

{ "error": "This submission was flagged as spam. If you believe this is a mistake, please reload the form and try again." }

POST

api

submit

{public_id}

curl -X POST "https://api.raykoi.com/api/v1/submit/p/YOUR_PUBLIC_ID" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"data": {"email": "user@example.com", "name": "Alice"}}'

import { createClient } from '@raykoi/sdk';

const client = createClient();
await client.form('YOUR_PUBLIC_ID').submit({
  email: 'user@example.com',
  name: 'Alice',
});

{
  "success": true,
  "submission_id": "sub_pub_1a2b3c",
  "submission_number": 42
}

{
  "error": "Validation failed",
  "errors": [
    { "field": "email", "fieldId": "email", "message": "Enter a valid email address", "type": "pattern" }
  ]
}

{ "error": "This submission was flagged as spam. If you believe this is a mistake, please reload the form and try again." }

Accepts application/json (the normal path — used by the SDK, submit.js, and raw fetch) or application/x-www-form-urlencoded (the plain <form method="POST"> no-JS path). The response shape changes based on which one you sent — see No JavaScript for that variant’s redirect-based behavior.

string

required

The form’s public ID, shown in the dashboard.

object

required

Field values keyed by field name. A file field’s value is a file reference object ({ path, originalFilename, mimeType, sizeBytes }) obtained from Get an Upload URL, not the raw file — see File Uploads.

string

Required if the form has CAPTCHA configured and you’re not authenticating with an API key. Acquired client-side from whichever provider the form uses.

object

Arbitrary extra data to attach to the submission — not validated against the schema, not shown as a form field, just stored alongside it.

string

No-JS path only. A same-origin (or allowed_origins-matching) URL to redirect to after success or failure.

string

Bearer rk_live_... — a secret API key. Authenticates the request as server-to-server and skips the CAPTCHA gate entirely.

string

A key unique to this logical submission attempt. Reusing it with the same payload returns the original result instead of creating a duplicate; reusing it with a different payload is rejected. Auto-generated by the SDK if you don’t supply one.

Response

boolean

Always true on a 201 — a non-2xx status is always an error body instead.

string

The submission’s public ID.

number

A per-form sequential number — useful for a human-readable reference (“submission #42”), not for sorting (use created_at).

curl -X POST "https://api.raykoi.com/api/v1/submit/p/YOUR_PUBLIC_ID" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"data": {"email": "user@example.com", "name": "Alice"}}'

import { createClient } from '@raykoi/sdk';

const client = createClient();
await client.form('YOUR_PUBLIC_ID').submit({
  email: 'user@example.com',
  name: 'Alice',
});

{
  "success": true,
  "submission_id": "sub_pub_1a2b3c",
  "submission_number": 42
}

{
  "error": "Validation failed",
  "errors": [
    { "field": "email", "fieldId": "email", "message": "Enter a valid email address", "type": "pattern" }
  ]
}

{ "error": "This submission was flagged as spam. If you believe this is a mistake, please reload the form and try again." }

​Response

Response