> For the complete Lynkow documentation index in agent-friendly format, see [llms.txt](/llms.txt).

# FormsService

**Publié le** : 2026-08-20
**Catégorie** : Services

# FormsService

Service for retrieving form schemas and submitting form data.

Accessible via `lynkow.forms`. Forms are dynamic, CMS-managed forms with
configurable fields, validation rules, and spam protection. The service
automatically handles honeypot anti-spam fields on submissions. Form schemas
are cached for 10 minutes (MEDIUM TTL).

Access via: `lynkow.forms`

## Methods

**3** methods

### `clearCache`

```typescript
clearCache(): void
```

Invalidate every cached form schema response. Call after an admin
mutation or on receipt of a `form.*` webhook so the next public
request re-fetches the latest field definitions (required fields,
validators, spam settings).

Does not affect form submissions, which are never cached.

Returns: `void`

```typescript
lynkow.forms.clearCache()
```

---

### `getBySlug`

```typescript
getBySlug(slug: string): Promise<Form>
```

Retrieves a form definition by its slug, including the field schema,
behavior settings (submit label, success message), and spam protection
configuration (honeypot/reCAPTCHA). Cached for 10 minutes.

| Parameter | Type | Description |
| --- | --- | --- |
| `slug` | `string` | The unique slug of the form (e.g. `'contact'`, `'newsletter'`, `'feedback'`) |


Returns: `Promise<Form>`

```typescript
const form = await lynkow.forms.getBySlug('contact')

// Render fields in order. Each field's `id` is the key you use later
// when submitting, not its label or any semantic name.
form.schema.fields.forEach(field => {
  console.log(field.id, field.type, field.label, field.required)
})

// Use schema.settings to wire the submit button and success message
console.log(form.schema.settings.submitLabel)

// Check spam protection config
if (form.recaptchaEnabled) {
  // Render reCAPTCHA widget using form.recaptchaSiteKey
}
```

---

### `submit`

```typescript
submit(slug: string, data: FormSubmitData, options?: SubmitOptions & BaseRequestOptions): Promise<FormSubmitResponse>
```

Submits form data to the API. Anti-spam honeypot fields (`_hp`, `_ts`) are
injected automatically by the SDK; you do not need to add them yourself.
If the form has reCAPTCHA enabled, pass the token via `options.recaptchaToken`.

| Parameter | Type | Description |
| --- | --- | --- |
| `slug` | `string` | The slug of the form to submit to (e.g. `'contact'`) |
| `data` | `FormSubmitData` | Key-value pairs keyed by `FormField.id` (auto-generated by<br>  the admin, e.g. `'field_1764776796820'`) from the schema returned by<br>  `getBySlug()`. Do not use semantic names like `'name'` or `'email'`<br>  unless those happen to be the actual field ids; field ids are not<br>  human-readable. Values can be `string`, `number`, `boolean`, or `File`. |
| `options` | `SubmitOptions & BaseRequestOptions` | Optional submission options:<br>  - `recaptchaToken`: the reCAPTCHA v3 token (required if reCAPTCHA is enabled on the form)<br>  - `fetchOptions`: custom fetch options (e.g. AbortSignal) |


Returns: `Promise<FormSubmitResponse>`

```typescript
const form = await lynkow.forms.getBySlug('contact')

// Build the payload with field.id as key. The SDK does not transform
// semantic names into ids; you must do that yourself based on the schema.
const data: Record<string, string> = {}
for (const field of form.schema.fields) {
  data[field.id] = readValueForField(field) // your UI binding
}

const result = await lynkow.forms.submit('contact', data)

if (result.status === 'pending') {
  // Show "check your email" confirmation
} else {
  // Show success message
  console.log(result.message)
}
```