Opprette en forespørsel

Start i Del-vinduet

Åpne det publiserte skjemaet ditt, klikk Del, og velg fanen Forespørsler. Kortet der gir deg alt du trenger for å gjøre det første kallet:

• Skjema-ID-en, med en kopiknapp.

• Et curl-utdrag og en MCP-prompt, begge bygget fra skjemaets faktiske feltnøkler — så eksempelet er allerede adressert til feltene dette skjemaet faktisk har.

• En Manuell-fane som oppretter én forespørsel for hånd, og Prøv det selv, som gjør det du fylte inn der om til en forespørsel i testmodus og gir deg lenken.

• En lenke videre til Forespørsler-siden, filtrert til dette skjemaet.

Steg 1 — Oppdag feltene

fields.list returnerer hvert felt i skjemaets nåværende publiserte versjon, med nøkkelen du adresserer det med, formen verdien tar, og hvilken bøtte det tilhører.

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer $FORMBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"method":"fields.list","params":{"formId":"j57..."}}'

{
  "ok": true,
  "data": {
    "published": true,
    "items": [
      { "key": "company_name", "type": "text", "title": "Company", "required": true, "prefillable": true },
      {
        "key": "company_size", "type": "select", "title": "Company size", "required": false, "prefillable": true,
        "options": [
          { "key": "1_50", "label": "1–50" },
          { "key": "51_200", "label": "51–200" }
        ]
      },
      { "key": "case_id", "type": "hidden", "title": "Case", "required": false, "prefillable": false, "context": true },
      { "key": "total", "type": "number", "title": "Total", "required": false, "prefillable": false, "calculated": true },
      { "key": "signature", "type": "signature", "title": "Sign here", "required": true, "prefillable": false }
    ],
    "hasMore": false
  }
}

• context: true merker et skjult felt. Verdien går i context, aldri i prefill; et skjult felts nøkkel i prefill avvises med UNKNOWN_FIELD_KEY.

• calculated: true merker et beregnet felt. Skjemaet regner ut verdien selv, så ingen kan sende inn en; du leser den tilbake under nøkkelen sin i answers.

• prefillable: false merker et felt ingen kan oppgi en verdi for: filopplasting, signatur, betaling, avtalebooking, og dokumentblokker. Mottakeren fyller ut spørsmålene selv. Skjulte felt og beregnede felt viser også prefillable: false: skjulte felt tar context, og beregnede felt tar ingenting.

• options lister valgene for et valgspørsmål. Send valgets nøkkel, ikke etiketten; etiketten er der slik at du kan koble valget du kjenner til, mot nøkkelen. En matrise lister sine rows og columns på samme måte.

• Gjentakende grupper kommer tilbake som én oppføring med type: “group”, repeating: true, og en liste med members.

Steg 2 — Opprett forespørselen

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer $FORMBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"method":"requests.create","params":{
        "formId":"j57...",
        "recipient":{"email":"ada@acme.com","name":"Ada"},
        "context":{"case_id":"CASE-9"},
        "prefill":{"company_name":"Acme","company_size":"51_200"},
        "readonly":["company_name"],
        "delivery":"email",
        "externalId":"run-42",
        "callbackUrl":"https://automation.example/webhook/resume-abc",
        "idempotencyKey":"run-42"}}'

{
  "ok": true,
  "data": {
    "id": "kd7...",
    "status": "pending",
    "url": "https://form.formbase.so/r/rq_...",
    "deliveryStatus": "queued",
    "expiresAt": 1794787200000,
    "createdAt": 1789379200000,
    "externalId": "run-42",
    "deduplicated": false
  }
}

deliveryStatus er “queued” når formbase sender invitasjonen på e-post, og “not_requested” når du leverer lenken selv.

Prefill, låste felt, og context

Tre ulike ting kan knyttes til en forespørsel, og å blande dem sammen er den vanligste første feilen.

Prefill

Startsvar for de synlige spørsmålene, slik at mottakeren gjennomgår og retter i stedet for å skrive fra bunnen. Alt du allerede vet om dem hører hjemme her — firmanavnet fra CRM-et ditt, beløpet fra fakturaen, fjorårets svar.

Låste felt

List opp en forhåndsutfylt nøkkel i readonly, så ser mottakeren verdien, men kan ikke endre den. Bruk det for fakta de bekrefter i stedet for oppgir — kontraktsnummeret, den avtalte prisen. Låsing gjelder per forespørsel: selve skjemaet er urørt, og det samme feltet er fritt redigerbart på neste forespørsel.

Hver låst nøkkel må også være forhåndsutfylt, og et låst, obligatorisk felt må forhåndsutfylles med noe som ikke er tomt — ellers ville mottakeren stå overfor et skjema de aldri kunne sende inn, og formbase avviser kallet i stedet for å skape den fellen.

Context

Tiltrodde verdier for skjemaets skjulte felt — et saksnummer, en kjørings-ID, et beløp. Context mater variabler, betinget logikk, beregnede felt og e-posttekst, kommer uendret tilbake i callbacken, og mottakeren kan ikke endre den. Det siste er forskjellen fra å så et skjult felt gjennom en URL på en offentlig lenke, der hvem som helst kan redigere spørrestrengen; forespørselslenker ignorerer URL-spørringsparametere fullstendig. Context-verdier må være en streng, et tall, eller en boolsk verdi.

Context er ikke fritekst: hver nøkkel må være et skjult felt i skjemaets publiserte versjon, og enhver annen nøkkel avvises med UNKNOWN_FIELD_KEY. Bokføring uten et skjult felt, som en kjørings-ID, hører i stedet hjemme i metadata.

Skjulte felt vises ikke på skjemaet, men en context-verdi er ikke hemmelig for mottakeren, som ser den overalt hvor skjemaet eller invitasjonen viser den: en omtale i skjemainnholdet eller e-postteksten, eller et synlig spørsmål som bruker det skjulte feltet som sin standardverdi. I det siste tilfellet ser mottakeren context-verdien forhåndsutfylt i det spørsmålet og kan redigere svaret. Selve context-verdien forblir uendret. En prefill for spørsmålets egen nøkkel vinner over standardverdien.

Metadata

Din egen bokføring — en kjørings-ID, en CRM-post-ID. Den når aldri selve skjemaet, så den kan ikke pipes inn i tekst eller leses av logikk; den blir bare med og kommer tilbake i hver callback og statusavlesning.

Verdiformer

Send verdier i formen type fra fields.list ber om. Feil form kommer tilbake som en valideringsfeil som navngir nøkkelen, forventet type, og — for valgspørsmål — verdiene som ville blitt godtatt.

Dokumenter

En dokumentblokk gir filer til respondenten. De opprinnelige filene er de samme for alle og blir alltid værende; en forespørsel legger til filer for sin ene mottaker under dem — kundens egen leiekontrakt, en kopi av ID-en å sjekke. Bytes reiser aldri gjennom selve API-kallet: last opp først, referer deretter.

1. 1

   Reserver opplastingen

   Kall documents.create med formId, name (1–200 tegn), contentType (PDF eller bilde), den eksakte størrelsen i bytes, og valgfritt en sha256 av filen (64 heksadesimale tegn). Du får tilbake en id og en uploadUrl som er gyldig i én time.

2. 2

   Last opp bytene

   PUT filen til uploadUrl med samme Content-Type. Ingenting er verifisert ennå.

3. 3

   Referer den på forespørselen

   Send documents: [{ documentId, name? }] med requests.create. formbase sjekker det opplastede objektet (størrelse, filsignatur, sha256 hvis du sendte en) før forespørselen opprettes, og mottakeren ser filen i blokken.

"documents": [
  { "documentId": "kn7...", "name": "Your lease contract" },
  { "documentId": "kn8..." }
]

name overstyrer visningsnavnet som ble lagret ved opplastingen. Har skjemaet mer enn én dokumentblokk, angir du målet med field, blokkens feltnøkkel (fields.list viser den, sammen med de faste dokumentene alle respondenter allerede får). Filene havner under de faste dokumentene: en forespørsel legger til filer, den erstatter aldri noen.

Grenser: bare PDF og bilder, 25 MB per dokument, 100 MB per forespørsel (DOCUMENTS_TOO_LARGE), og maks 20 dokumenter per blokk medregnet de faste (DOCUMENTS_TOO_MANY). Filene teller mot arbeidsområdens lagringskvote og frigjøres når forespørslene som refererer dem, faller ut av skjemaets oppbevaringsperiode. Innsendingen registrerer listen mottakeren så under blokkens feltnøkkel, så callbacken forteller deg nøyaktig hvilke filer denne personen fikk.

Resten av alternativene

Testmodus

Send test: true for å prøve ut hele koblingen før en ekte kjøring. En testforespørsel er ekte på alt som betyr noe for koblingen: lenken åpnes og kan fullføres, callbacken fyrer som vanlig, og requests.get returnerer svarene. Det den aldri gjør, er å nå noen eller noe du måtte rydde opp etter:

• Ingen invitasjon og ingen påminnelse sendes, uansett hva delivery sier. Send påminnelse avvises på den, og den bruker ingenting av din månedlige kvote.

• Callbacken bærer “test”: true, slik at arbeidsflyten din kan forgrene seg på det eller ignorere hendelsen.

• Innsendingen lagres, men teller ikke: verken mot din månedlige kvote (en test fullføres selv når kvoten er brukt opp), og den vises aldri i skjemaets innsendingstall, innsendinger-fanen, eksporter, eller integrasjonene dine. Ingen blir varslet.

• Forespørselen er skjult fra Forespørsler-siden bak Vis testforespørsler, utelatt fra forespørselstrakten i Analyse, og utelatt fra requests.list-svaret med mindre du sender includeTest: true som parameter.

• Lenken lukkes innen 24 timer, selv når expiresAt ber om lengre tid; expiresAt i svaret sier når. På Free kan et workspace opprette 10 testforespørsler per dag. Den neste feiler med RATE_LIMITED og årsaken TEST_REQUEST_LIMIT_REACHED, og retryAfterMs sier når du kan prøve igjen. Pro og Business har ingen daglig grense.

Prøv det selv i Del-vinduet er denne modusen med ett klikk: den tar utkastet fra Manuell-fanen, lar mottaker og levering stå tomt, og gir deg lenken å åpne selv.

Hva en forespørsel koster

Hver plan har én månedlig kvote som deles av begge kanaler: en innsending via offentlig lenke bruker én enhet, og det gjør også hver forespørsel du oppretter — uansett om mottakeren svarer, ignorerer den, eller du kansellerer den. Innsendingen en forespørsel samler inn er allerede betalt for og teller ingen steder. Gratis inkluderer 1 000 enheter i måneden, Pro og Business 50 000. Ved taket mislykkes requests.create med UPGRADE_REQUIRED og årsak MONTHLY_ALLOWANCE_REACHED; forespørsler du allerede har opprettet, kan fortsatt besvares.

På Gratis bruker en forespørsel opprettet med “delivery”: “email” også én av kontoens 10 gratis invitasjoner. De nullstilles aldri; når de er brukt opp, mislykkes e-postlevering med UPGRADE_REQUIRED og årsak FREE_INVITATIONS_USED.

Idempotens

Send den samme idempotencyKey med den samme forespørselskroppen, og du får den opprinnelige forespørselen tilbake, med deduplicated: true og den opprinnelige lenken — ingen ny forespørsel, ingen ny e-post. Gjenbruk nøkkelen med en annen forespørselskropp, og formbase avviser med IDEMPOTENCY_CONFLICT i stedet for å gjette hvilken du mente. Nøkler gjelder per arbeidsområde og respekteres i 30 dager; etter det starter samme nøkkel en ny forespørsel.

I et arbeidsflytverktøy er kjørings-ID-en den naturlige nøkkelen: en kjøring som prøves på nytt etter et nettverksglipp, plukker opp forespørselen den allerede opprettet.

Hastighetsbegrensning

requests.create og documents.create deler et budsjett på 60 kall i minuttet, telt per API-token (eller per bruker, ved et kall gjort uten ett). En etterslep du tømmer, bør holde sitt eget tempo; en byge over budsjettet avvises, men kan prøves på nytt.

Egendefinerte domener

Hvis skjemaet allerede er publisert på ett av dine egendefinerte domener, utstedes forespørselslenker der automatisk — https://forms.dittselskap.com/r/rq_…. Navngi domainId eksplisitt når skjemaet er publisert på mer enn ett. Domenet må tilhøre samme arbeidsområde som skjemaet.

Hva mottakeren ser

Nøyaktig skjemaet du utformet — samme tema, samme logo, samme språk — med verdiene deres på plass, låste felt skrivebeskyttet, og ingen captcha å løse. Når de sender inn, får de din takkeside. Kommer de tilbake til lenken etterpå, får de resultatsiden i stedet for et tomt skjema.

Det finnes ingen melding fra automatiseringen din på siden. Alt mottakeren trenger å bli fortalt hører hjemme i selve skjemaet, der du kan personalisere det ved å nevne en context-verdi eller et forhåndsutfylt felt.

En AI-agent følger de samme to stegene som fields_list og request_create, med de samme alternativene — inkludert documents og domainId. Se Forespørsler på MCP-serveren.