Send en forespørsel med REST API-et

Du trenger et publisert skjema. Denne guiden bruker det som ble bygget i Bygg et skjema med en AI-agent: firmanavn, kontakt-e-post, MVA-nummer, et ja- eller nei-spørsmål om betalingsbetingelser, og en filopplasting. Hver metode og hvert alternativ brukt her er beskrevet i API-metoder.

1. Opprett et API-token

I formbase, åpne OAuth og API-nøkler i arbeidsområdets sidepanel og opprett et token. Verdien vises én gang. Behold det i en miljøvariabel, ikke i koden din:

export FORMBASE_TOKEN='fb_...'

Et token når det ene arbeidsområdet det ble opprettet i. Hvert kall under er en POST til samme URL med tokenet i Authorization-headeren; kroppen navngir metoden og parameterne dens.

2. Finn skjema-IDen

Åpne skjemaet i editoren. Skjema-IDen er delen av adressen etter /forms/:

https://app.formbase.so/<workspace ID>/forms/jx75hdx8vb5hy1x85gm17nqgkn8f674g/edit

Kommandoene under bruker denne guidens skjema-ID. Sett inn din egen i stedet.

3. List feltnøklene

En forespørsel fyller inn spørsmål, og svarene kommer tilbake, etter feltnøkkel. Spør skjemaet om nøklene sine i stedet for å gjette dem fra titlene:

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": "jx75hdx8vb5hy1x85gm17nqgkn8f674g"}}'

Svaret lister hvert spørsmål i det publiserte skjemaet. Forkortet:

{
  "ok": true,
  "data": {
    "published": true,
    "items": [
      { "key": "company_name", "type": "text", "title": "Company name", "required": true, "prefillable": true },
      { "key": "contact_email", "type": "email", "title": "Contact email", "required": true, "prefillable": true },
      { "key": "vat_number", "type": "text", "title": "VAT number", "required": false, "prefillable": true },
      {
        "key": "do_you_accept_our_30_day_payment_terms", "type": "radio", "title": "Do you accept our 30-day payment terms?", "required": true, "prefillable": true,
        "options": [{ "key": "yes", "label": "Yes" }, { "key": "no", "label": "No" }]
      },
      { "key": "certificate_of_incorporation", "type": "file", "title": "Certificate of incorporation", "required": true, "prefillable": false }
    ],
    "hasMore": false
  }
}

For å forhåndsutfylle et valgspørsmål, send alternativets key, her “yes”, ikke etiketten dets. Et spørsmål med prefillable: false, som filopplastingen, kan bare mottakeren svare på. De andre flaggene er forklart under fields.list.

4. Opprett en testforespørsel

Send forespørselen til Ada Lovelace, med firmanavnet fylt inn og låst. test: true gjør den til en testforespørsel: den sender aldri e-post til noen og teller ingen steder, så du kan gjenta dette steget så ofte du vil, med en ny idempotencyKey hver gang.

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": "jx75hdx8vb5hy1x85gm17nqgkn8f674g",
      "recipient": { "email": "ada@acme.example", "name": "Ada Lovelace" },
      "prefill": { "company_name": "Analytical Engines Ltd" },
      "readonly": ["company_name"],
      "externalId": "supplier-2043",
      "idempotencyKey": "supplier-2043",
      "test": true
    }
  }'

• prefill fyller inn svar mottakeren fortsatt kan endre. En nøkkel i readonly er også låst.

• externalId er din egen id for dette stykket arbeid, som et leverandørnummer. Den kommer tilbake på hver lesing og callback.

• idempotencyKey gjør et nytt forsøk trygt. Hvis koden din sender det samme kallet to ganger, returnerer formbase den første forespørselen med deduplicated: true i stedet for å opprette en ny.

Svaret bærer forespørsels-IDen og lenken for mottakeren:

{
  "ok": true,
  "data": {
    "id": "m17ayhcnj9xvzkff3atek49bdd8f6872",
    "status": "pending",
    "url": "https://form.formbase.so/r/rq_...",
    "deliveryStatus": "not_requested",
    "externalId": "supplier-2043",
    "deduplicated": false,
    "createdAt": 1790539225370,
    "expiresAt": 1793131225370
  }
}

deliveryStatus: “not_requested” betyr at formbase ikke sendte noen e-post; du leverer lenken selv. For å la formbase sende invitasjonen og påminnelsene, legg til “delivery”: “email”, som krever en Pro- eller Business-plan. Se Invitasjoner, påminnelser og utløp. Hvis skjemaet har Send påminnelser på, får en ekte forespørsel med en mottaker-e-post likevel de planlagte påminnelsene; legg til “reminders”: [] for å sende ingen.

5. Fullfør den og les svarene

Åpne url i en nettleser. Firmanavnet er fylt inn og låst; svar på resten og send inn. Les så forespørselen tilbake med IDen:

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer $FORMBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"method": "requests.get", "params": {"requestId": "m17ayhcnj9xvzkff3atek49bdd8f6872"}}'

Når status er completed, bærer svaret to kart nøkkelsatt etter feltnøkkel. answers er for kode: et valgsvar er alternativets nøkkel, et filsvar er en liste med filer med nedlastings-URL-er. display er for mennesker: etiketter og filnavn.

"answers": {
  "company_name": "Analytical Engines Ltd",
  "do_you_accept_our_30_day_payment_terms": "yes",
  "certificate_of_incorporation": [{ "name": "certificate-of-incorporation.pdf", "type": "application/pdf", "size": 635, "url": "https://api.formbase.so/api/storage/..." }]
},
"display": {
  "company_name": "Analytical Engines Ltd",
  "do_you_accept_our_30_day_payment_terms": "Yes",
  "certificate_of_incorporation": "certificate-of-incorporation.pdf"
}

Å spørre igjen og igjen til statusen endres, fungerer for en test, men ikke i produksjon. Gi forespørselen en callbackUrl, og formbase kaller deg når den avsluttes; neste guide setter det opp.

Neste