**גרסאות API** · [V2 (Latest)](/integrations/v2/docs?lang=he) · **V1**

> **גרסה זו של ה־API מיושנת.** לחיבורים חדשים יש להשתמש בגרסה העדכנית ביותר. [לתיעוד העדכני](/integrations/v2/docs?lang=he)

# Forms

OpenAPI 3.0.3 · API 1.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v1",
    "description": "API"
  }
]
```

Transactional forms — both the form DEFINITIONS (structure, products, fields) and the SUBMISSIONS people send. Scopes: `forms:read`/`forms:write` for definitions, `forms_submit:read`/`forms_submit:write` for submissions, `forms_submit:validate` to accept/refuse a submission (which emails the registrant).

## פעולות

## GET /forms

List forms

`list_forms`

Required scope: `forms:read`. Lists the org's forms (light fields). Paginated.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "forms:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  },
  "description": "Number of results per page"
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Opaque cursor returned by the previous request"
}
```

```json
{
  "name": "active",
  "in": "query",
  "schema": {
    "type": "boolean"
  },
  "description": "Filter by active state."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormDefinition"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /forms

Create a form

`create_form`

Required scope: `forms:write`. Creates a form DEFINITION from an editor business object. The transpilation of `additionalFields` and the storage of `products` are handled server-side. Returns the created form in editor shape.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "forms:write",
  "additional": []
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/FormInput"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/FormInput"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "VALIDATION_ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "VALIDATION_ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /forms/{id}

Get a form definition (products, calendars, content)

`get_form`

Required scope: `forms:read`. Returns the same payload the public website uses to render the form (transpiled `content`), scoped to the API key's organisation. To EDIT a form, read `/forms/{id}/edit` instead.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "forms:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/FormDefinition"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## PATCH /forms/{id}

Edit a form

`update_form`

Required scope: `forms:write`. Partial update of a form DEFINITION (editor business object). Only the fields supplied change; omit `products`/`additionalFields` to leave them untouched, send them to replace the whole set. Returns the updated form in editor shape.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "forms:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/FormUpdateInput"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/FormInput"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "VALIDATION_ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "VALIDATION_ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms:write",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /forms/{id}/edit

Get a form in EDITOR shape

`get_form_edit`

Required scope: `forms:read`. Returns the editor business object (products inlined, `additionalFields` rebuilt) — the exact shape `POST /forms` and `PATCH /forms/{id}` accept. Read this before editing.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "forms:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/FormInput"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /forms-submit

List form submissions

`list_forms_submit`

Required scope: `forms_submit:read`

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "forms_submit:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  },
  "description": "Number of results per page"
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Opaque cursor returned by the previous request"
}
```

```json
{
  "name": "createdAfter",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "date-time"
  },
  "description": "Filter: created after this date (ISO 8601)"
}
```

```json
{
  "name": "createdBefore",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "date-time"
  },
  "description": "Filter: created before this date (ISO 8601)"
}
```

```json
{
  "name": "formId",
  "in": "query",
  "schema": {
    "type": "string"
  }
}
```

```json
{
  "name": "state",
  "in": "query",
  "schema": {
    "type": "string",
    "enum": [
      "SUBMIT",
      "VALIDE",
      "INVALIDE"
    ]
  },
  "description": "Filter by decision state. SUBMIT = awaiting a decision."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormSubmit"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms_submit:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /forms-submit

Submit a form

`create_forms_submit`

Required scope: `forms_submit:write`. Creates a `forms_submit` document, applies all the same side-effects as the public website (contact CRM sync, totals, promo codes, notifications, payment link). When a payment is needed, the response `url` points to the hosted payment page. Edit mode (`data.extra.editId`) is not supported through this endpoint.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "forms_submit:write",
  "additional": []
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/SubmitRequest"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/SubmitResponse"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "MISSING_FORM_ID or EDIT_MODE_NOT_SUPPORTED",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "MISSING_FORM_ID or EDIT_MODE_NOT_SUPPORTED"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "FORM_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "FORM_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms_submit:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## POST /forms-submit/with-payment

Submit a form and create the payment link in one call

`create_forms_submit_with_payment`

Required scopes: `forms_submit:write` AND `paiements:write`. Same behavior as `POST /forms-submit` — convenience endpoint to make the scope intent explicit when the caller knows a payment is expected. The payment URL is returned in `url`.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "forms_submit:write",
  "additional": []
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/SubmitRequest"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/SubmitResponse"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "MISSING_FORM_ID or EDIT_MODE_NOT_SUPPORTED",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "MISSING_FORM_ID or EDIT_MODE_NOT_SUPPORTED"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPES",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPES"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "FORM_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "FORM_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms_submit:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /forms-submit/{id}

Get a form submission

`get_forms_submit`

Required scope: `forms_submit:read`

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "forms_submit:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/FormSubmit"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms_submit:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /forms-submit/{id}/validate

Accept a submission (⚠️ emails the registrant)

`validate_submission`

Required scope: `forms_submit:validate`. Sets the submission to VALIDE and SENDS a confirmation email to the registrant — a real-world side effect, hence its own scope. Idempotent: returns `already:true` if it was already VALIDE.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "forms_submit:validate",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms_submit:validate",
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": false,
    "warn": true
  }
}
```

## POST /forms-submit/{id}/invalidate

Refuse a submission (no email)

`invalidate_submission`

Required scope: `forms_submit:validate`. Sets the submission to INVALIDE. Does NOT email anyone. Idempotent: returns `already:true` if it was already INVALIDE.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "forms_submit:validate",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms_submit:validate",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## סכמות

```json
{
  "components": {
    "parameters": {
      "LimitParam": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200,
          "default": 50
        },
        "description": "Number of results per page"
      },
      "CursorParam": {
        "name": "cursor",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "Opaque cursor returned by the previous request"
      },
      "IdParam": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
        },
        "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
      },
      "CreatedAfterParam": {
        "name": "createdAfter",
        "in": "query",
        "schema": {
          "type": "string",
          "format": "date-time"
        },
        "description": "Filter: created after this date (ISO 8601)"
      },
      "CreatedBeforeParam": {
        "name": "createdBefore",
        "in": "query",
        "schema": {
          "type": "string",
          "format": "date-time"
        },
        "description": "Filter: created before this date (ISO 8601)"
      }
    },
    "schemas": {
      "FormDefinition": {
        "type": "object",
        "description": "Public-facing definition of a form (products, calendars, transpiled HTML).",
        "properties": {
          "id": {
            "type": "string"
          },
          "organisation": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "SIMPLE",
              "COMPLEX"
            ]
          },
          "title": {
            "type": "string"
          },
          "active": {
            "type": "boolean"
          },
          "withPaiement": {
            "type": "boolean"
          },
          "autoValid": {
            "type": "boolean"
          },
          "requirePaiementValidation": {
            "type": "boolean"
          },
          "content": {
            "type": "string",
            "description": "Transpiled HTML when type=SIMPLE."
          },
          "afficheUrl": {
            "type": "string",
            "description": "Absolute URL of the poster/cover image shown atop the form (present when set)."
          },
          "aiContentBlockId": {
            "type": "string",
            "description": "Id of the AI content block rendered as a rich banner at the top of the form (present when set)."
          },
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormProduct"
            }
          },
          "calendars": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "expired": {
            "type": "boolean",
            "description": "True if the linked PE session is no longer active."
          }
        }
      },
      "FormProduct": {
        "type": "object",
        "description": "A product line of a COMPLEX form (purchase item).",
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "montant": {
            "type": "number",
            "description": "Unit amount in major units (e.g. euros)"
          },
          "cerfa": {
            "type": "boolean"
          },
          "simple_stock": {
            "type": "integer",
            "nullable": true
          },
          "activeReducedPrice": {
            "type": "boolean"
          },
          "reducedPercent": {
            "type": "number",
            "nullable": true
          },
          "reducedExpireAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "position": {
            "type": "integer"
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "hasMore": {
            "type": "boolean"
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "FormInput": {
        "type": "object",
        "description": "Editor business object of a form DEFINITION — the shape you send to create or edit a form, and the shape returned by GET /forms/{id}/edit. A form is a flexible transactional engine: a submission may be a ticketing order, a multi-product purchase, a family registration, a donation, etc. Distinguish the PAYER (who submits) from BENEFICIARIES (via product additionalFields). On a partial PATCH, omit `products`/`additionalFields` to leave them as-is; send them to replace the whole set.",
        "required": [
          "title"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "Public form title (required)."
          },
          "url": {
            "type": "string",
            "description": "Public slug (lowercase, no accents, spaces→\"-\"). Optional."
          },
          "description": {
            "type": "string",
            "description": "Internal description (admin only)."
          },
          "afficheUrl": {
            "type": "string",
            "description": "Poster/cover image URL or hosted filename shown at the top of the form. Adds WhatsApp share metadata. Send \"\" to remove it. Coexists with aiContentBlockId (both may be set)."
          },
          "aiContentBlockId": {
            "type": "string",
            "nullable": true,
            "description": "Id of an AI content block (ai_content_blocks) rendered as a rich HTML banner at the very top of the form, above the identity fields. Optional — omit to leave unchanged, send \"\"/null to remove. Independent from afficheUrl (the poster image): a form may show both."
          },
          "autoValid": {
            "type": "boolean",
            "description": "true = submissions auto-validated; false = manual validation."
          },
          "withPaiement": {
            "type": "boolean",
            "description": "Enable online payment. When false, all payment fields below are ignored."
          },
          "paiementType": {
            "type": "string",
            "enum": [
              "PAIEMENT",
              "ABONNEMENT",
              "MONTHLY"
            ],
            "description": "Billing model: PAIEMENT=one-off; ABONNEMENT=limited instalments; MONTHLY=recurring monthly. Requires withPaiement=true."
          },
          "onePaiement": {
            "type": "boolean",
            "description": "Force a single payment (no deposit). Only with paiementType=PAIEMENT."
          },
          "deposit": {
            "type": "number",
            "description": "Fixed deposit amount. paiementType=PAIEMENT and onePaiement=false."
          },
          "depositPercent": {
            "type": "number",
            "description": "Deposit as a percentage (0-100). Same dependency as `deposit`."
          },
          "abonnementMaxMonth": {
            "type": "integer",
            "description": "Max number of instalments (≥2). paiementType=ABONNEMENT."
          },
          "aboMonthInfinite": {
            "type": "boolean",
            "description": "Subscription with no end. paiementType=MONTHLY."
          },
          "aboMonthMin": {
            "type": "integer",
            "description": "Min subscription months (≥1). MONTHLY + aboMonthInfinite=false."
          },
          "aboMonthMax": {
            "type": "integer",
            "description": "Max subscription months (≥ aboMonthMin). MONTHLY + aboMonthInfinite=false."
          },
          "paiementMethods": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Alternative manual methods, e.g. [\"CHEQUE\",\"VIREMENT\",\"ESPECES\"]."
          },
          "requirePaiementValidation": {
            "type": "boolean",
            "description": "Validation conditioned on online payment. Requires withPaiement=true."
          },
          "autoValidOtherPaiementMethod": {
            "type": "boolean",
            "description": "Auto-validate alternative-method payments. Requires requirePaiementValidation=true."
          },
          "allowZeroAmount": {
            "type": "boolean",
            "description": "Allow a submission whose total is 0."
          },
          "identity": {
            "type": "string",
            "enum": [
              "SIMPLE"
            ],
            "description": "Contact identification level. SIMPLE = full name + email + phone."
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "CRM categories auto-applied to every contact who submits."
          },
          "globalStock": {
            "type": "integer",
            "nullable": true,
            "description": "Shared stock that overrides per-product stocks."
          },
          "allowNoProduct": {
            "type": "boolean",
            "description": "Allow submitting without selecting any product."
          },
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormProductInput"
            },
            "description": "Buyable items. Use distinct products for distinct prices."
          },
          "additionalFields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormAdditionalField"
            },
            "description": "Global custom fields (once per submission)."
          }
        }
      },
      "FormProductInput": {
        "type": "object",
        "description": "A product line of a form (a buyable item/ticket/option). PRICE VARIATION IS DONE ONLY VIA DISTINCT PRODUCTS — never via tariff options on a single product.",
        "required": [
          "label",
          "title",
          "montant"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Product id (omit on create; matched by id or label on edit)."
          },
          "label": {
            "type": "string",
            "description": "Internal unique label within the form."
          },
          "title": {
            "type": "string",
            "description": "Public title shown to the buyer."
          },
          "description": {
            "type": "string",
            "description": "Internal description (admin only)."
          },
          "montant": {
            "type": "number",
            "description": "Unit price in MAJOR units (e.g. euros). 0 = free. Interpreted monthly when paiementType=MONTHLY."
          },
          "cerfa": {
            "type": "boolean",
            "description": "Whether this product is eligible for a tax receipt."
          },
          "active": {
            "type": "boolean",
            "description": "Whether the product is active (default true)."
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "CRM categories applied to the contact ONLY when this product is selected."
          },
          "simple_stock": {
            "type": "integer",
            "description": "Per-product stock limit. Ignored when globalStock is set."
          },
          "additionalFields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormAdditionalField"
            },
            "description": "Per-unit fields, repeated for each quantity bought."
          }
        }
      },
      "FormAdditionalField": {
        "type": "object",
        "description": "A dynamic field added to a form (or to a product). Two scopes: GLOBAL fields (at the form root) appear once per submission; PRODUCT fields (inside a product) repeat per purchased unit. Only collect per-unit info as a product field; everything about the whole order is a global field.",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "TEXT-INPUT",
              "TEXTAREA-INPUT",
              "SELECT-INPUT",
              "CHECKBOX-INPUT",
              "DOCS-INPUT",
              "DATE-INPUT",
              "TITLE",
              "CONTACT-INPUT",
              "FREE-AMOUNT-INPUT"
            ],
            "description": "Field kind. TEXT-INPUT=free single-line text; TEXTAREA-INPUT=free multi-line text (optional `height` in px); SELECT-INPUT=dropdown (needs `values`); CHECKBOX-INPUT=yes/no; DOCS-INPUT=file upload (needs `doctype`); DATE-INPUT=date/time picker (optional `picker`/`dateFilter`/`range`/`defaultNow`, defaults to a plain date); TITLE=visual separator (no data; uses `__title_tag`+`__text`); CONTACT-INPUT=secondary CRM contact (name+email+phone); FREE-AMOUNT-INPUT=donor-chosen amount (GLOBAL only, requires withPaiement=true, never inside a product)."
          },
          "required": {
            "type": "boolean",
            "description": "Whether the field is mandatory."
          },
          "__label": {
            "type": "string",
            "description": "Visible label of the field."
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Options for SELECT-INPUT (required for that type)."
          },
          "doctype": {
            "type": "string",
            "enum": [
              "IMG",
              "PDF",
              "ZIP"
            ],
            "description": "Allowed upload kind for DOCS-INPUT."
          },
          "height": {
            "type": "integer",
            "description": "TEXTAREA-INPUT only: fixed height of the text area in pixels (optional)."
          },
          "picker": {
            "type": "string",
            "enum": [
              "Date & Heure",
              "Uniquement les Années",
              "Uniquement les Mois",
              "Uniquement l'heure"
            ],
            "description": "DATE-INPUT only: granularity. Omit for a plain day date (DD/MM/YYYY). \"Date & Heure\"=date+time; \"Uniquement les Années\"=year; \"Uniquement les Mois\"=month; \"Uniquement l'heure\"=time."
          },
          "dateFilter": {
            "type": "string",
            "enum": [
              "Antérieur à aujourd'hui",
              "Ultérieur à aujourd'hui",
              "Aujourd'hui & antérieur à aujourd'hui",
              "Aujourd'hui & ultérieur à aujourd'hui"
            ],
            "description": "DATE-INPUT only: restrict selectable dates relative to today (optional)."
          },
          "range": {
            "type": "boolean",
            "description": "DATE-INPUT only: pick a start→end range instead of a single value (optional)."
          },
          "defaultNow": {
            "type": "boolean",
            "description": "DATE-INPUT only: pre-fill with the current date/time (optional)."
          },
          "__title_tag": {
            "type": "string",
            "enum": [
              "h1",
              "h2",
              "h3",
              "h4",
              "h5"
            ],
            "description": "Heading level for TITLE."
          },
          "__text": {
            "type": "string",
            "description": "Heading text for TITLE."
          }
        }
      },
      "FormUpdateInput": {
        "type": "object",
        "description": "Partial form definition update. Only supplied fields change; no field is required.",
        "properties": {
          "title": {
            "type": "string",
            "description": "Public form title (required)."
          },
          "url": {
            "type": "string",
            "description": "Public slug (lowercase, no accents, spaces→\"-\"). Optional."
          },
          "description": {
            "type": "string",
            "description": "Internal description (admin only)."
          },
          "afficheUrl": {
            "type": "string",
            "description": "Poster/cover image URL or hosted filename shown at the top of the form. Adds WhatsApp share metadata. Send \"\" to remove it. Coexists with aiContentBlockId (both may be set)."
          },
          "aiContentBlockId": {
            "type": "string",
            "nullable": true,
            "description": "Id of an AI content block (ai_content_blocks) rendered as a rich HTML banner at the very top of the form, above the identity fields. Optional — omit to leave unchanged, send \"\"/null to remove. Independent from afficheUrl (the poster image): a form may show both."
          },
          "autoValid": {
            "type": "boolean",
            "description": "true = submissions auto-validated; false = manual validation."
          },
          "withPaiement": {
            "type": "boolean",
            "description": "Enable online payment. When false, all payment fields below are ignored."
          },
          "paiementType": {
            "type": "string",
            "enum": [
              "PAIEMENT",
              "ABONNEMENT",
              "MONTHLY"
            ],
            "description": "Billing model: PAIEMENT=one-off; ABONNEMENT=limited instalments; MONTHLY=recurring monthly. Requires withPaiement=true."
          },
          "onePaiement": {
            "type": "boolean",
            "description": "Force a single payment (no deposit). Only with paiementType=PAIEMENT."
          },
          "deposit": {
            "type": "number",
            "description": "Fixed deposit amount. paiementType=PAIEMENT and onePaiement=false."
          },
          "depositPercent": {
            "type": "number",
            "description": "Deposit as a percentage (0-100). Same dependency as `deposit`."
          },
          "abonnementMaxMonth": {
            "type": "integer",
            "description": "Max number of instalments (≥2). paiementType=ABONNEMENT."
          },
          "aboMonthInfinite": {
            "type": "boolean",
            "description": "Subscription with no end. paiementType=MONTHLY."
          },
          "aboMonthMin": {
            "type": "integer",
            "description": "Min subscription months (≥1). MONTHLY + aboMonthInfinite=false."
          },
          "aboMonthMax": {
            "type": "integer",
            "description": "Max subscription months (≥ aboMonthMin). MONTHLY + aboMonthInfinite=false."
          },
          "paiementMethods": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Alternative manual methods, e.g. [\"CHEQUE\",\"VIREMENT\",\"ESPECES\"]."
          },
          "requirePaiementValidation": {
            "type": "boolean",
            "description": "Validation conditioned on online payment. Requires withPaiement=true."
          },
          "autoValidOtherPaiementMethod": {
            "type": "boolean",
            "description": "Auto-validate alternative-method payments. Requires requirePaiementValidation=true."
          },
          "allowZeroAmount": {
            "type": "boolean",
            "description": "Allow a submission whose total is 0."
          },
          "identity": {
            "type": "string",
            "enum": [
              "SIMPLE"
            ],
            "description": "Contact identification level. SIMPLE = full name + email + phone."
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "CRM categories auto-applied to every contact who submits."
          },
          "globalStock": {
            "type": "integer",
            "nullable": true,
            "description": "Shared stock that overrides per-product stocks."
          },
          "allowNoProduct": {
            "type": "boolean",
            "description": "Allow submitting without selecting any product."
          },
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormProductInput"
            },
            "description": "Buyable items. Use distinct products for distinct prices."
          },
          "additionalFields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormAdditionalField"
            },
            "description": "Global custom fields (once per submission)."
          }
        }
      },
      "FormSubmit": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "organisation": {
            "type": "string"
          },
          "form": {
            "type": "string",
            "description": "Form id"
          },
          "state": {
            "type": "string"
          },
          "data": {
            "type": "object"
          },
          "total": {
            "type": "number",
            "description": "Expected total of the registration, in MAJOR currency units."
          },
          "devise": {
            "type": "string",
            "description": "Currency code."
          },
          "paye": {
            "type": "number",
            "readOnly": true,
            "description": "Amount actually paid (sum of COMPLETED payments), in MAJOR units."
          },
          "reste": {
            "type": "number",
            "readOnly": true,
            "description": "Remaining to pay (max(0, total - paye)), in MAJOR units."
          },
          "paiements": {
            "type": "array",
            "readOnly": true,
            "description": "COMPLETED payments of this submission (amounts in MAJOR units). Only on GET /forms-submit/{id}.",
            "items": {
              "type": "object",
              "properties": {
                "amount": {
                  "type": "number"
                },
                "method": {
                  "type": "string",
                  "nullable": true
                },
                "datetime": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "datetime": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SubmitRequest": {
        "type": "object",
        "required": [
          "formId"
        ],
        "properties": {
          "formId": {
            "type": "string",
            "description": "ID of the target form (must belong to the API key's organisation)."
          },
          "devise": {
            "type": "string",
            "description": "Submission currency. Defaults to the form's currency.",
            "nullable": true
          },
          "data": {
            "type": "object",
            "description": "Free-form submission payload. Common keys: `identity` (contact object), `__promo`, `__paiementMethod`, `[CONTACT]_*`, `[HAZKARA]_*`, `[CHILD]_*`, `[FREE_AMOUNT]_*`, `<productId>_quantity`. Note: `data.extra.editId` is rejected for integrations.",
            "additionalProperties": true
          }
        }
      },
      "SubmitResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/FormSubmit"
          },
          "url": {
            "type": "string",
            "nullable": true,
            "description": "Payment link URL when the submission requires a payment, otherwise null."
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format: `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
