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, med en ny idempotencyKey hver gang (på Free opptil 10 ganger per dag). Lenken lukkes innen 24 timer.

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. En Gratis-konto får 10 invitasjoner for å prøve det, uten påminnelser; etter det mislykkes kallet med FREE_INVITATIONS_USED. 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