# Opprette et skjema og en forespørsel i ett kall

Send blokkene med forespørselen: Formstep bygger skjemaet, publiserer det og returnerer lenken, uten editoren innimellom.

## Når du bør bruke det

En forespørsel peker vanligvis på et skjema noen har bygget i editoren og publisert. Når spørsmålene avhenger av saken, sender avsenderen dem med i stedet: `requests.create` tar `form` i stedet for `formId`. Formstep bygger et vanlig skjema av blokkene, publiserer det og oppretter forespørselen i ett steg, så enten finnes begge eller ingen av dem. Vi kaller det et **skjema fra forespørsel**.

Fortsett å bruke `formId` for et skjema du sender til mange med samme innhold og vil utforme for hånd i editoren. Bruk `form` når en automatisering bestemmer hva som skal spørres om.

## Kallet

```bash
curl -X POST https://api.formstep.io/api/v1 \
  -H "Authorization: Bearer $FORMSTEP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"method":"requests.create","params":{
        "form":{
          "name":"Documents and fee for your mortgage application",
          "logo":{"type":"image","url":"https://acme.example/logo.png"},
          "cover":{"type":"color","color":"#0f4c81"},
          "emoji":"🏦",
          "blocks":[
            {"type":"paragraph","content":"Upload the two documents and pay the processing fee."},
            {"type":"file","key":"payslips","title":"Your last two payslips","maxFiles":2},
            {"type":"payment","key":"fee","title":"Processing fee","amount":40,"currency":"EUR"},
            {"type":"scheduleAppointment","key":"call","title":"Pick a time for our call","eventType":"15 min call"}]},
        "recipient":{"email":"ada@example.com","name":"Ada"},
        "delivery":"email",
        "idempotencyKey":"call-8841"}}'
```

Alt annet ved forespørselen beholder sin betydning: `recipient`, `prefill`, `context`, `readonly`, `delivery`, påminnelser, utløp, `callbackUrl`, `test` og `idempotencyKey` kontrolleres mot det nye skjemaet akkurat som mot et skjema bygget for hånd. Responsen får i tillegg skjemaet, med nøklene svarene kommer tilbake under:

```json
{
  "id": "kd7...",
  "status": "pending",
  "url": "https://form.formstep.io/r/rq_...",
  "form": {
    "id": "j58...",
    "name": "Documents and fee for your mortgage application",
    "reused": false,
    "fields": [
      { "key": "payslips", "type": "file" },
      { "key": "fee", "type": "payment" },
      { "key": "call", "type": "schedule-appointment" }
    ]
  }
}
```

For å forhåndsutfylle et valgspørsmål i samme kall sender du valgnøkler, som for ethvert skjema. Et valgs nøkkel avledes fra etiketten, så `Self-employed` blir `self_employed`. En etikett i stedet for en nøkkel feiler med `INVALID_PREFILL_VALUE`, som lister de gyldige nøklene.

## Skjemaobjektet

| Felt | Hva det gjør |
| - | - |
| name | Påkrevd, 1 til 100 tegn. Navnet på dashbordet og i nettleserfanen, det samme for hver mottaker. Tilpass med prefill og context, aldri med navnet. |
| blocks | Påkrevd, 1 til 200 blokker, i rekkefølgen skjemaet viser dem. Blokkene i kolonnene til en rad og feltene i en gjentakende gruppe teller også. |
| language | Skjemaets UI-språk. Standard: engelsk. |
| logo, cover, emoji | Merkevaren din, sendt med hver forespørsel. logo: { "type": "icon", "name": "HeartIcon" } eller { "type": "image", "url": "https\://…" }. cover: { "type": "color", "color": "#0f4c81" } eller { "type": "image", "url": "https\://…", "offsetY": 50 }. emoji: én emoji ved siden av navnet. Se nedenfor. |
| theme | Et utseende per fargemodus: { "light": "solarized-light", "dark": "dracula" }. Hver modus tar en forhåndsinnstilling-ID, gratis på alle planer, eller et helt temaobjekt slik MCP-verktøyet formTheme\_set tar det, som krever Pro-planen. |
| settings | Skjemaoppførselen innstillingssiden styrer: merkevare, et verifisert e-postdomene (emailDomainId), e-poster til eieren og til den som svarer med teksten deres, påminnelsesplanen, invitasjons-e-posten, videresendingen og lagringstiden. Felt etter nøkkel: respondentNotificationTo er nøkkelen til et e-postspørsmål, redirectQueryParams kobler en parameter til en feltnøkkel. E-postteksten er ren tekst med {{key}}-plassholdere. Ingen sperre med passord eller innlogging og ingen delingslenkeinnstilling som robotbeskyttelse eller endringer etter innsending: en forespørsel har sin egen lenke. Alle andre nøkler avvises. |
| translations | Skjemaet på flere språk, med en språkvelger for mottakeren: { "de": { "Your name": "Ihr Name" } }, hver tekst i skjemaet med teksten slik blokkene skrev den som nøkkel. Se nedenfor. |

## Blokker

En blokk tar parameterne til det tilsvarende `editor_insert*`-verktøyet på [MCP-serveren](https://docs.formstep.io/no/developers/mcp-server/) , uten `formId` og `after`, pluss en valgfri `key`. Uten nøkkel utledes den fra tittelen, så “Fullt navn” blir `fullt_navn`. En parameter blokken ikke kjenner, avvises i stedet for å bli ignorert.

| Kategori | Typer |
| - | - |
| Spørsmål | text, contact, number, date, time, radio, checkbox, select, switch, rating, linearScale, matrix, ranking, pictureChoice, file, signature, decision |
| Dokumenter | documents, for å vise filer mottakeren leser eller signerer |
| Betalinger og bookinger | payment, scheduleAppointment |
| Innhold | header, paragraph, image (src-URL), embedded, table (cells fyller den), list, row (columns: blokkene i hver kolonne, 2 til 6 kolonner, og widths i prosent). En valgfri key lar logikk vise eller skjule blokken. |
| Struktur | pageDivider, repeatingGroup (fields: spørsmålene i gruppen som blokker, hvert med sin nøkkel), hiddenField (key er påkrevd: det er context-nøkkelen), calculatedField (name er nøkkelen), logic |

Tekst i header og paragraph, listepunkter og tabellceller forstår `bold`, `italic`, `struck`, `<u>underlined</u>`, `code`, `$$equation$$`, `text`, `<span color=“red” background=“yellow” font=“font-georgia” size=“1.25”>…</span>` med fargene, skriftene og størrelsene fra editorens verktøylinje, og `{{key}}`, som viser verdien til feltet med den nøkkelen. Formateringer kan nøstes; en markør uten motpart blir vanlig tekst. En kolonne i en rad tar alle blokker unntatt pageDivider, logic, hiddenField, calculatedField, repeatingGroup, row og scheduleAppointment. En `decision`-blokk tar `title` og `labels` for godkjenn, avslå og endringer på skjemaets språk.

Blokker refererer til hverandre med nøkkel, aldri med element-ID: en `logic`-blokk tar `rule` slik `editor_insertLogic` gjør, med feltnøkler der den vil ha ID-er, alternativenes etiketter som betingelsesverdier og sidenavn for `setNextPage`.

### Betalinger

En `payment`-blokk tar `amount` og `currency`, eller `amountFromField`: nøkkelen til et skjult felt eller et tallspørsmål. Med et skjult felt sender hver forespørsel sitt eget beløp i `context`, så ett skjema tar betalt riktig beløp fra hver kunde:

```json
{
  "form": {
    "name": "Pay your invoice",
    "blocks": [
      { "type": "hiddenField", "key": "invoice_total" },
      { "type": "payment", "key": "invoice", "title": "Invoice", "currency": "EUR", "amountFromField": "invoice_total" }
    ]
  },
  "recipient": { "email": "ada@example.com" },
  "context": { "invoice_total": 1200 }
}
```

Et tallspørsmål som setter beløpet, må være påkrevd og ha en `min` over 0, slik at ingen kommer til checkout med et tomt beløp, null eller et negativt beløp.

Skjemaet tar betalt via arbeidsområdets standard Stripe-konto, eller kontoen `connection` peker på. En person [kobler til Stripe én gang for arbeidsområdet](https://docs.formstep.io/no/building-forms/payment-collection/#connect-stripe); en automatisering kan ikke. Uten en brukbar konto feiler kallet og forteller deg hvor du kobler den til.

### Bookinger

En `scheduleAppointment`-blokk tar `eventType`, tittelen eller ID-en til en hendelsestype på arbeidsområdets [Cal.com](https://docs.formstep.io/no/integrations/cal-com/)-tilkobling, og `connection` når arbeidsområdet har flere. Formstep slår opp hendelsestypen når forespørselen opprettes. `prefill: { name, email }` angir spørsmålene som fyller ut bookingen med svarene sine.

## Merkevaren din

En automatisering kan ikke finne på utseendet ditt, så du gir det til den én gang, og den sender det med hver forespørsel: `logo`, `cover` og `emoji` ved siden av blokkene, og `theme` for farger og skrift.

| Felt | Tar |
| - | - |
| logo | Et ikon fra byggeren, { "type": "icon", "name": "HeartIcon" }, eller ditt eget bilde, { "type": "image", "url": "https\://…/logo.png" }. |
| cover | En ensfarget bakgrunn, { "type": "color", "color": "#0f4c81" }, eller et bilde, { "type": "image", "url": "https\://…/cover.jpg", "offsetY": 50 }, der offsetY fra 0 til 100 velger hvilken del av et høyt bilde som vises. |
| emoji | Én emoji, vist ved siden av skjemanavnet. |

Hvert bilde, også `src` i en bildeblokk, må være en offentlig JPEG, PNG eller WebP. Formstep henter hvert bilde én gang når skjemaet opprettes og beholder sin egen kopi, så skjemaet og PDF-ene av innsendingene varer lenger enn kilden. En URL som ikke kan hentes, får kallet til å feile med `INLINE_FORM_IMAGE_UNREACHABLE`, som nevner feltet. Uten merkevare ser skjemaet ut som et nytt skjema fra dashbordet.

## Oversettelser

`translations` publiserer skjemaet på flere språk med en gang, og mottakeren får språkvelgeren et oversatt skjema har: `{ "de": { "Your name": "Ihr Name", "Order for **{{customer}}**": "Bestellung für **{{customer}}**" } }`. Hver tekst i skjemaet må være med, med teksten nøyaktig slik blokkene skrev den som nøkkel: spørsmålstitler, alternativer, plassholdere, overskrifter, avsnitt, listepunkter, tabellceller, gruppenavn og knappetekster. Formatering og `{{key}}` blir stående som i kilden. En tekst som mangler, får kallet til å feile med `INLINE_FORM_TRANSLATION_MISSING`, som lister tekstene som må legges til. E-postteksten oversettes ikke.

## Én definisjon, ett skjema

Et senere kall med det samme `form`-objektet gjenbruker det samme skjemaet, og responsen sier `“reused”: true`. Hundre forespørsler med én definisjon gir ett skjema, med ett sett svar å eksportere. Endrer du en blokk, navnet, merkevaren eller en oversettelse, blir det et nytt skjema; forespørsler som allerede er sendt, beholder skjemaet de ble opprettet med. Et skjema du lukker eller avpubliserer, blir ikke gjenbrukt: neste kall med samme definisjon lager et nytt.

> **Tilpass med prefill og context**
>
> Legg kundens navn, fakturanummeret eller beløpet i `prefill` og `context`, aldri i skjemanavnet, en tittel eller et fast beløp. En definisjon som endres per kunde, gir et nytt skjema per kunde. Sett `key` på hvert spørsmål: en avledet nøkkel følger tittelen, så et spørsmål med ny tittel svarer under en ny nøkkel. Et arbeidsområde lager høyst 300 nye inline-skjemaer per dag; etter det feiler et kall som ville laget et nytt skjema med `RATE_LIMITED`, mens kall som gjenbruker et skjema fortsatt virker.

Når et kall lager et nytt skjema selv om et åpent skjema fra forespørsel har de samme blokktypene i samme rekkefølge, nevner svaret det skjemaet i `form.similarForm`. Som oftest skyldes det et endret navn eller en endret tittel. For å lese alle svar på ett skjema fra forespørsel, list innsendingene i stedet for å lese hver forespørsel.

## På dashbordet

Et skjema fra en forespørsel hører til forespørselen, så det ligger på forespørselens side i stedet for på Skjemaer-siden. Siden viser svarene etter feltnøkkel, og **Forhåndsvis** åpner skjemaet slik mottakeren så det, utfylt med svarene deres. En lenke til editoren eller innsendingene for et slikt skjema åpner i stedet Forespørsler-siden, filtrert på det skjemaet. Agenter ser fortsatt disse skjemaene i `form_list`, og API-et nekter å endre dem.

Et skjema fra en forespørsel har ingen delingslenke, og du kan ikke legge til en: forespørslene er eneste vei inn, og callbacken har med hvert svar. Det har heller ingen integrasjoner.

Fordi det ikke har noen egen side, slettes et inline-skjema aldri for hånd. Det følger med den siste forespørselen sin: når du [sletter en forespørsel](https://docs.formstep.io/no/requests/managing-requests/#delete), eller skjemaets oppbevaringsperiode tar den, og ingen andre forespørsler fortsatt bruker skjemaet, slettes skjemaet også.

## Når kallet avvises

Hver avvisning er en `VALIDATION_ERROR` med en `details.reason` automatiseringen din kan forgrene på. Ingenting opprettes.

| Årsak | Hva du gjør |
| - | - |
| FORM\_SOURCE\_MISSING / FORM\_SOURCE\_AMBIGUOUS | Send nøyaktig én av formId og form. |
| INLINE\_FORM\_INVALID | En blokk eller et felt i form er ugyldig. details.issues nevner hver av dem. |
| INLINE\_FORM\_DUPLICATE\_KEY | To blokker får samme nøkkel. Gi én av dem sin egen nøkkel. |
| INLINE\_FORM\_UNKNOWN\_KEY | En logikkregel, amountFromField eller prefill for en booking nevner en nøkkel ingen blokk har. |
| INLINE\_FORM\_AMOUNT\_MISSING | Send et positivt tall for beløpsfeltet i context. |
| INLINE\_FORM\_CONNECTION\_MISSING | Stripe eller Cal.com er ikke koblet til. details.connectUrl er siden en person åpner én gang for å koble til. |
| INLINE\_FORM\_EVENT\_TYPE\_NOT\_FOUND | Ingen hendelsestype i Cal.com passer. Feilen lister opp de som finnes. |
| INLINE\_FORM\_IMAGE\_UNREACHABLE | En bilde-URL er ikke en offentlig JPEG, PNG eller WebP. details.field nevner den. Bruk en URL alle kan åpne, eller fjern bildet. |
| INLINE\_FORM\_TRANSLATION\_MISSING | En oversettelse mangler tekster skjemaet har. details.missing lister dem, slik de er skrevet i blokkene. |
| INLINE\_FORM\_PUBLISH\_ISSUES | Publiseringen avviste skjemaet, for eksempel en hendelsestype som ikke kan bookes fra et skjema. |

## Fra en agent

På MCP-serveren tar `request_create` det samme `form`. Før en agent bygger et skjema med en betaling eller en booking, leser den `workspaceConnection_list`: den viser de tilkoblede Stripe- og Cal.com-kontoene og, når en mangler, lenken en person må åpne én gang. `scheduler_listEventTypes` lister hendelsestypene en booking kan nevne, og `paymentConnection_setDefault` endrer standard Stripe-konto. I REST-API-et heter de samme tre `connections.list`, `scheduler.listEventTypes` og `paymentConnections.setDefault`.

[Opprette en forespørsel](https://docs.formstep.io/no/requests/creating-requests/) — Forhåndsutfylling, låsing og context for alle skjemaer.

[Feltnøkler](https://docs.formstep.io/no/requests/field-keys/) — Hvordan nøkler utledes og holdes stabile.

[Callbacks og signering](https://docs.formstep.io/no/requests/callbacks/) — Motta svarene når forespørselen avsluttes.

[Betalingsinnkreving](https://docs.formstep.io/no/building-forms/payment-collection/) — Koble til Stripe for arbeidsområdet.