Skip to main content

Custom Form & Application Engine

The AVCI CMS Custom Form Engine enables administrators to design dynamic, schema-driven forms directly from the panel and collect structured submissions from storefront users without writing frontend code.

Beyond standard surveys, Custom Forms power Platform Application Workflows (MERCHANT_APPLICATION, BRAND_APPLICATION, ORGANIZATION_APPLICATION), featuring automated status tracking, review workspaces, smart attribute mapping, and 1-click entity provisioning upon approval.

Architecture Note:
Custom Forms are distinct from Contact Forms. Contact Forms manage basic inquiries and support messages, while Custom Forms manage structured entity-mapped applications and lifecycle approval workflows.

The x-avci-client header is mandatory for all requests.


Form Purposes & Lifecycle Actions​

PurposeDescriptionAutomatic Action on Approval
STANDARDGeneral inquiry, registration, or data collectionNone (status transition only)
MERCHANT_APPLICATIONVendor onboarding for marketplace sellersCreates Merchant, assigns owner, sets MERCHANT_ONBOARDING_SETUP
BRAND_APPLICATIONBrand registry and manufacturer applicationCreates Brand, links owner, sets BRAND_SETUP
ORGANIZATION_APPLICATIONCooperative / trade chamber applicationCreates Organization, links owner, sets ORGANIZATION_SETUP
SURVEYCustomer feedback and satisfaction metricsUpdates form conversion & statistical aggregates

Smart Attribute Mapping (mappedAttributeId)​

Fields inside a Custom Form can be linked directly to an entity attribute via mappedAttributeId. When an application is approved, responses for mapped fields are automatically converted into the target entity's normalized EAV attributes array:

{
"fields": [
{
"id": "tax_id_field",
"name": "taxNumber",
"label": "Corporate Tax Identification Number",
"type": "TEXT",
"required": true,
"mappedAttributeId": "660c1d2e3f4a5b6c7d8e9f01"
}
]
}

1. Storefront & Public APIs​

1.1 Fetch Form Schema​

Retrieves the form title, description, and list of input fields for dynamic frontend rendering.

  • Endpoint: GET /customForm/:formId
  • Auth Requirement: x-avci-client

Example Response:

{
"status": "success",
"data": {
"_id": "660c1d2e3f4a5b6c7d8e9a01",
"title": "Marketplace Vendor Application",
"purpose": "MERCHANT_APPLICATION",
"fields": [
{
"id": "fld_1",
"name": "businessName",
"label": "Business Legal Name",
"type": "TEXT",
"required": true
},
{
"id": "fld_2",
"name": "city",
"label": "Registered City",
"type": "SELECT",
"options": ["Istanbul", "Ankara", "Izmir"]
}
]
}
}

1.2 Submit Form Responses​

Submits the user's answers against the dynamic schema.

  • Endpoint: POST /customForm/submit/:formId
  • Auth Requirement: x-avci-client

Request Body:

{
"businessName": "Artisan Leather Crafts Ltd.",
"city": "Izmir"
}

Example Response:

{
"status": "success",
"data": {
"submissionId": "660c1d2e3f4a5b6c7d8e9b99",
"status": "PENDING",
"submittedAt": "2026-11-11T12:00:00.000Z"
}
}

1.3 Check Prior Submission​

Verifies if the authenticated user has already submitted a form limited to one entry:

  • Endpoint: GET /customForm/has-submission/:formId
  • Auth Requirement: x-avci-client + Authorization: Bearer <token>

2. Management & Backoffice APIs​

Requires workspace administrator credentials (Authorization: Bearer <token>).

2.1 Form Management​

  • List Forms: GET /customForm?page=1&limit=20
  • Get Form Details: GET /customForm/:formId
  • Create Form: POST /customForm
  • Update Form: PUT /customForm/:formId
  • Delete Form: DELETE /customForm/:formId

2.2 Submissions Oversight​

  • List Submissions: GET /customForm/:formId/submissions?status=PENDING&page=1&limit=20
  • Submission Review Detail: GET /customForm/:formId/submissions/:subId
  • Update Status: PUT /customForm/:formId/submissions/:subId/status
    • Body: { "status": "UNDER_REVIEW", "note": "Identity documents verified" }
    • Valid states: PENDING, UNDER_REVIEW, APPROVED, REJECTED, CANCELLED

2.3 Process Approval Action​

Executes the form's automated approval lifecycle:

  • Endpoint: POST /customForm/submissions/:submissionId/process
  • Action: Provisions the entity (Merchant, Brand, Organization), links mapped EAV attributes, creates initial credentials, and assigns onboarding setup stages.
{
"status": "success",
"data": {
"success": true,
"entityId": "660c1d2e3f4a5b6c7d8e9c55",
"entityType": "MERCHANT",
"status": "APPROVED"
}
}

2.4 Statistics & Audit Logs​

  • Get Form Analytics: GET /customForm/:formId/statistics
  • Get Submission Logs: GET /customForm/:submissionId/logs

3. SDK Code Examples​

TypeScript SDK (@avci/sdk)​

import { AvciCMS } from 'avcicms';

const avci = new AvciCMS({
apiKey: process.env.AVCI_API_KEY!,
clientId: process.env.AVCI_CLIENT_ID!,
});

// 1. Storefront: fetch schema and submit application
const { data: form } = await avci.customForm.getSchema('form_vendor_application');
const { data: submission } = await avci.customForm.submit('form_vendor_application', {
businessName: 'Artisan Woodworks',
city: 'Istanbul',
});

// 2. Backoffice: approve application & auto-provision merchant
await avci.customForm.updateSubmissionStatus(
'form_vendor_application',
submission.submissionId,
'APPROVED',
'Approved after legal compliance review'
);
await avci.customForm.processApproval(submission.submissionId);

Python SDK (avcicms)​

from avcicms import AvciCMS

client = AvciCMS(
api_key="your_api_key",
project_id="your_project_id",
)

# 1. Fetch form submissions in review
submissions = client.custom_form.get_submissions(
form_id="660c1d2e3f4a5b6c7d8e9a01",
status="PENDING",
page=1,
)

# 2. Process approval and provision entity
for sub in submissions.get("docs", []):
client.custom_form.process_approval(sub["_id"])