Lesson 5

Add Records with the Quickbase REST API

Move beyond reading Quickbase data and create a new People record from a Code Page. This lesson introduces the REST record payload, Quickbase's CREATE endpoint, and the JSON acknowledgment Quickbase returns after the record is created.

Lesson Objective

Send Data to Quickbase and Confirm What It Created

Build a JSON payload from an HTML form, send it to the Quickbase REST API, inspect the response metadata, retrieve the newly assigned Record ID#, and reload the People table to verify the new record.

The Important Change

Until Now, Data Has Been Traveling Toward JavaScript

Lessons 1 through 4 concentrated primarily on asking Quickbase for information. Lesson 5 reverses that direction for the first time: JavaScript now sends record values to Quickbase.

Previous Lessons

Quickbase
    ↓
JSON / XML
    ↓
JavaScript
    ↓
HTML

Quickbase supplied information and the Code Page displayed or manipulated it.

Lesson 5

HTML Form
    ↓
JavaScript
    ↓
JSON Payload
    ↓
Quickbase

The Code Page supplies values and asks Quickbase to create a new record.

People Table

The Same Fields, Now Moving in the Other Direction

The People table has not changed. We are still working with the same Quickbase Field IDs used throughout the lab.

Field	Field ID	CREATE Behavior
Record ID#	`3`	Quickbase assigns this automatically.
Name	`6`	JavaScript supplies the form value.
Age	`7`	JavaScript supplies the numeric value.
Favorite Color	`8`	JavaScript supplies the form value.

Lesson 5 Roadmap

Five Steps from Form to Quickbase Record

This lesson builds the CREATE workflow one piece at a time. Use this roadmap to see where you are in the process and how each step leads to the next.

Build the payload

Organize the People field values into the JSON structure Quickbase expects.

Take control of the form

Let JavaScript handle the submitted values instead of a normal browser form submission.

Send the CREATE request

Send the record payload to the Quickbase REST API.

Read Quickbase's response

Inspect the JSON acknowledgment and retrieve the Record ID# Quickbase assigned.

Complete the workflow

Report success, reset the form, and reload the People table to confirm the new record.

Build the Quickbase Record Payload

The form gives JavaScript three values: Name, Age, and Favorite Color. Those values must be converted into the record structure expected by the Quickbase REST API.

function buildPersonPayload(name, age, favoriteColor) {
  return {
    to: TABLE_DBID,

    data: [
      {
        [FIELD_IDS.name]: {
          value: name,
        },

        [FIELD_IDS.age]: {
          value: Number(age),
        },

        [FIELD_IDS.favoriteColor]: {
          value: favoriteColor,
        },
      },
    ],
  };
}

Notice what is missing.

Field ID 3, Record ID#, is not included in the payload. Quickbase creates the new record and assigns its Record ID# automatically.

Payload Anatomy

Quickbase Field IDs Become JSON Object Keys

{
  to: TABLE_DBID,

  data: [
    {
      6: { value: "Walter" },
      7: { value: 44 },
      8: { value: "Orange" }
    }
  ]
}

to

Identifies the destination Quickbase table.

data

Contains the records Quickbase should process.

fieldId.value

Identifies each Quickbase field and its submitted value.

Take Control of the HTML Form

The form should not perform a normal browser submission. JavaScript intercepts the submit event, reads the field values, and handles the request through the Quickbase REST API.

async function addPerson(event) {
  event.preventDefault();

  const name =
    document.getElementById("personName").value.trim();

  const age =
    document.getElementById("personAge").value;

  const favoriteColor =
    document.getElementById("personColor").value.trim();

  // Build and submit the Quickbase request...
}

Why event.preventDefault()?

It prevents the browser from performing the form's normal page submission. JavaScript remains in control of the interaction.

Send the CREATE Request

The REST request resembles the READ request from Lesson 1B, but it uses a different endpoint and sends a record payload instead of a query definition.

READ

POST /v1/records/query

Ask Quickbase to return records.

CREATE — New in Lesson 5

POST /v1/records

Send field values to Quickbase for writing.

const response = await fetch(
  "https://api.quickbase.com/v1/records",
  {
    method: "POST",

    headers: {
      "QB-Realm-Hostname": REALM,
      Authorization:
        `QB-TEMP-TOKEN ${temporaryToken}`,
      "Content-Type": "application/json",
    },

    body: JSON.stringify(payload),
  },
);

Aha Moment

The API Call Is a Request and an Acknowledgment

Sending the JSON payload is only half of the operation. Quickbase processes the request and then returns a structured JSON response describing what happened.

JavaScript
    │
    │  REQUEST
    │  "Create this record"
    ▼
Quickbase
    │
    │  Creates the record
    │  Assigns Record ID#
    ▼
JSON Response
    │
    │  ACKNOWLEDGMENT
    │  "Here is what happened."
    ▼
JavaScript

Read Quickbase's JSON Response

Just as the READ endpoint returns JSON records, the CREATE endpoint returns JSON describing the result of the write operation.

const data = await response.json();

if (!response.ok) {
  throw new Error(
    `HTTP ${response.status}: ${JSON.stringify(data)}`,
  );
}

Quickbase Response Metadata

Quickbase Tells Us Which Record It Created

The response includes a metadata object. For this lesson, the most important property is createdRecordIds.

const createdRecordId =
  data.metadata?.createdRecordIds?.[0];

What JavaScript sent

6 → Walter
7 → 44
8 → Orange

→

What Quickbase added

Record ID# → 12
Name       → Walter
Age        → 44
Color      → Orange

Connect the Lessons

Record ID# Comes Full Circle

We have been reading Field ID 3 since the beginning of the REST lessons. Lesson 5 finally shows where that value originates when a record is created.

CREATE REQUEST

Field 6 → Name
Field 7 → Age
Field 8 → Favorite Color

        ↓

QUICKBASE

Creates the record
Assigns Record ID#

        ↓

CREATE RESPONSE

metadata.createdRecordIds
        ↓
       [12]

        ↓

NEXT READ

record["3"].value
        ↓

Record ID# appears in the People table

Complete the CREATE Workflow

After Quickbase confirms the new record, report the assigned Record ID#, clear the form, and then reload the People table.

status.textContent =
  `${name} was added to Quickbase as Record ID ${createdRecordId}.`;

event.target.reset();

await loadPeople();

Why use await loadPeople()?

The CREATE workflow waits for the follow-up READ operation to finish. The newly created Quickbase record is then rendered from the table's current data.

Complete Flow

CREATE Followed by READ

Fill out form
      ↓
Submit
      ↓
addPerson(event)
      ↓
event.preventDefault()
      ↓
Read form values
      ↓
getTemporaryToken()
      ↓
buildPersonPayload(...)
      ↓
POST /v1/records
      ↓
Quickbase creates record
      ↓
JSON acknowledgment
      ↓
metadata.createdRecordIds
      ↓
Show Record ID#
      ↓
Reset form
      ↓
await loadPeople()
      ↓
POST /v1/records/query
      ↓
Render updated People table

One Important REST Detail

Both operations use the HTTP method POST, but they do different things because they use different Quickbase endpoints and different request contracts.

Operation	Endpoint	Meaning
READ	`/v1/records/query`	Give JavaScript Quickbase records.
CREATE	`/v1/records`	Give Quickbase record values to write.

Lesson 5 Complete

You Can Now Create Quickbase Records from a Code Page

You built a Quickbase record payload, sent it through the REST API, interpreted Quickbase's JSON acknowledgment, retrieved the new Record ID#, reset the form, and refreshed the table to verify the new record.

Next: Lesson 6 — Edit Records

The next lesson will use the identity of an existing Quickbase record to change values that are already stored in the People table.