Form Requests

Form Requests let you generate targeted, AI-powered forms on demand via API. Your system provides situational context — like “suite check-in, needs parking preferences” — and SingleForm’s AI generates a tailored form from a template. You get back a deep link that you deliver to your user through your own channels. When they complete the form in the SingleForm mobile app, the data goes straight to your webhook.

How It Works

1. Choose a template — select from predefined categories (medical, legal, contact, etc.)
2. Hydrate with context — call the API with a natural language prompt describing the situation
3. AI generates the form — a tailored form schema is created from the template + your context
4. Create an instance — get a deep link with an expiration and your reference ID
5. You deliver the link — send it via your own email, SMS, booking system, etc.
6. Data goes to your webhook — the recipient fills out the form and data flows directly to your server

SingleForm never sees or stores your recipients’ contact information. You call the API, get a link, and handle delivery yourself.

Why Form Requests?

A regular form link is static — every user sees the same fields. Form requests are dynamically generated per situation:

• A hotel generates a different check-in form for a suite guest (parking, late checkout) vs a standard room
• A dental office generates intake forms with different fields for a new patient vs a returning patient
• A law firm generates disclosure forms tailored to the specific case type

The AI takes your template’s domain knowledge and combines it with the context you provide to produce a form that fits the exact situation.

Templates

Templates define the structure and domain context for form generation. Each template includes:

Listing Templates

curl https://api.singleform.ai/api/form-requests/templates

{
  "templates": [
    {
      "id": "tmpl_abc123",
      "name": "Patient Intake",
      "slug": "patient-intake",
      "category": "MEDICAL",
      "description": "Collect patient information for new visits",
      "icon": "medical",
      "examplePrompt": "Add insurance and allergy fields"
    }
  ]
}

Creating a Form Request

Send a template slug, your context as a prompt, and your business name:

curl -X POST https://api.singleform.ai/api/form-requests \
  -H "Content-Type: application/json" \
  -d '{
    "templateSlug": "hotel-checkin",
    "prompt": "Guest booked a suite. Include parking preferences and late checkout options.",
    "name": "Suite Check-In",
    "businessName": "The Grand Hotel",
    "userId": "user_abc123",
    "webhookUrl": "https://hotel.com/webhooks/checkin"
  }'

The AI generates a complete form schema using the template’s domain knowledge combined with your context. Locked fields (defined in the template) are automatically included.

Response

{
  "formRequest": {
    "id": "fr_abc123",
    "name": "Suite Check-In",
    "slug": "suite-check-in",
    "category": "HOSPITALITY",
    "consentMessage": "The Grand Hotel is requesting your check-in information for your upcoming suite reservation.",
    "generatedSchema": { "..." }
  },
  "tokensUsed": { "input": 1200, "output": 800 }
}

Creating an Instance

Generate a deep link tied to your internal reference ID:

curl -X POST https://api.singleform.ai/api/form-requests/fr_abc123/instance \
  -H "Content-Type: application/json" \
  -d '{
    "referenceId": "booking-2024-4821",
    "expiresInMinutes": 120
  }'

Response

{
  "instance": {
    "id": "fri_abc123",
    "status": "PENDING",
    "deepLinkToken": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "deepLink": "singleform://form-request/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "expiresAt": "2024-01-15T14:00:00.000Z"
  }
}

Send the deepLink to your user through your own channels — email, SMS, in-app notification, booking confirmation, etc. When they open it, the SingleForm mobile app loads the form with your branding and business verification status.

Instance Lifecycle

Receiving Responses

When a recipient submits the form, the data is sent to your webhook URL:

{
  "type": "form_request_response",
  "instanceId": "fri_abc123",
  "referenceId": "booking-2024-4821",
  "formRequestName": "Suite Check-In",
  "values": {
    "firstName": "Jane",
    "lastName": "Doe",
    "checkInDate": "2024-01-15",
    "parkingNeeded": true,
    "lateCheckout": "2pm",
    "specialRequests": "Extra pillows please"
  },
  "completedAt": "2024-01-15T13:30:00.000Z"
}

Use the referenceId to match the response back to your internal records (e.g. a booking ID, appointment, or case number).

Regenerating a Form

If you want to adjust the generated form, regenerate it with an updated prompt:

curl -X POST https://api.singleform.ai/api/form-requests/fr_abc123/regenerate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Also ask about dietary restrictions for the welcome dinner"
  }'

The AI regenerates the schema from the original template context with your new instructions.

AI Field Resolution

When a recipient opens a form request in the mobile app, SingleForm can use AI to pre-resolve fields based on the user’s stored data. This helps users fill forms faster while maintaining privacy.

The resolution process is privacy-preserving — actual user data values are never sent to the AI. Only anonymized metadata (field categories and types) is shared, and the AI determines the best action for each field:

Each resolution includes a confidence level (high, medium, or low) and an explanation.

Privacy Model

SingleForm’s form request system is designed so that your users’ personal data never touches SingleForm’s servers:

• Your context is situational, not personal — you describe the scenario (“suite check-in, needs parking”), not the person
• Deep links are opaque — UUID-based tokens that can’t be enumerated
• Data flows directly to your webhook — form submissions go from the mobile app to your server
• AI field resolution is anonymized — only field type metadata is sent to the AI, never actual values
• Delivery is your responsibility — you send the link through your own channels, so SingleForm never sees recipient contact information