Airtable Implementation Packet

Field mappings, required tables, automation ownership, and the fastest safe implementation sequence for live Airtable wiring.

Working packetField mappingCutover planValidated20 sections46 table rows1 code blocksLast updated March 9, 2026docs/airtable-implementation-packet.md

Document Summary

Execution-first packet for the Airtable working session and persistence cutover.

Airtable Implementation Packet

Date: March 9, 2026 Purpose: keep the Airtable cutover plan current as execution moves from discovery into validation and remaining implementation

Goal

Track the highest-value Airtable-backed workflows and the remaining implementation gaps:

  1. Parent intake submissions
  2. Doula application submissions
  3. Doula availability responses and client-visible matches
  4. Interview persistence
  5. Payment ledger persistence

Critical Reality Check

The repo currently has two conflicting Airtable models:

  1. AIRTABLE-SCHEMA.md

    • old documentation
    • describes a generic single-base, 9-table design

  2. airtable.ts

    • current code reality
    • expects a multi-base setup:
      • AIRTABLE_PARENTS_BASE_ID
      • AIRTABLE_DOULAS_BASE_ID
      • AIRTABLE_PRODUCTS_BASE_ID
      • AIRTABLE_MARKETING_BASE_ID
      • AIRTABLE_ADMIN_BASE_ID
    • currently targets these real table names:
    • Parent Intake Forms
    • Parent-Doula Matches
    • Active Contracts
    • Parents Payments
    • Interview Status
    • client conversion now happens in-place on Parent Intake Forms using Client Status plus structured metadata appended to Note
      • TBC Doula Database
      • Provider Directory
      • amazon products
      • Blog Posts
      • Newsletter Signups
      • Admin Payments
    • live approval workflow now also stores:
      • structured approval metadata in TBC Doula Database.Notes
      • mentor roster labels in Assigned Mentor/Mentees
      • provider-directory publication state through Provider Directory

Current Recommendation

Use the current code model in airtable.ts as the baseline for tomorrow.

Do not try to redesign the entire Airtable architecture in the same session unless you explicitly want to stop and do a schema migration pass first.

The fastest safe path from here is:

  1. Validate the two public write paths safely against live Airtable
  2. Add only the missing fields/tables needed for invoices and remaining finance ops
  3. Keep using the current multi-base model
  4. Update docs and tracker state as each workflow turns live

Safety Rule Before Any Live Write Test

Do not run a real production Airtable write just because API auth works.

Reason:

  • Parent Database has active create/update-triggered automations
  • those automations can send Gmail messages, post to Slack, append to Google Sheets, and trigger contract/availability workflows

That means a single test insert can create real side effects.

Allowed test modes, in order:

  1. sandbox/test base copy
  2. production base with relevant automations temporarily disabled
  3. production base with explicit operator approval for the side effects

Non-negotiables:

  • no Airtable delete operations without explicit user approval
  • no bulk test inserts
  • no write tests against Parent Intake Forms while assuming they are “safe”

Environment Variables To Confirm

These are the Airtable environment variables the app currently expects:

AIRTABLE_API_KEY=
AIRTABLE_PARENTS_BASE_ID=
AIRTABLE_DOULAS_BASE_ID=
AIRTABLE_PRODUCTS_BASE_ID=
AIRTABLE_MARKETING_BASE_ID=
AIRTABLE_ADMIN_BASE_ID=

For the next implementation wave, the required ones are:

  • AIRTABLE_API_KEY
  • AIRTABLE_PARENTS_BASE_ID
  • AIRTABLE_DOULAS_BASE_ID
  • AIRTABLE_MARKETING_BASE_ID
  • AIRTABLE_ADMIN_BASE_ID

AIRTABLE_PRODUCTS_BASE_ID is still optional for intake/application/matching work.

Current Local-Only Flows To Replace

Parent intake form

  • UI/form: parent-intake-form.tsx
  • server write path: route.ts
  • current behavior: posts through the API into Airtable, but live production verification is still handled carefully because create-triggered automations are active

Doula application form

  • UI/form: doula-application-form.tsx
  • server write path: route.ts
  • current behavior: posts through the API into TBC Doula Database, with live validation still handled carefully because webhook side effects are active

Doula availability responses

  • API write path: route.ts
  • client hook: useDoulaMatchResponses.ts
  • current behavior: reads and writes available / not_available responses against Parent-Doula Matches
  • requested-doula-unavailable branch: /api/matches now sends the single client-facing email path server-side and stamps requestedDoulaUnavailableEmailSentAt into the match metadata so retries do not duplicate the notification
  • privacy boundary: doula email and phone should not be stored on Parent-Doula Matches; match rows should only carry doula identity needed for workflow state, while private contact info stays on TBC Doula Database

Doula approval, directory publication, and mentorship

  • approval write path: route.ts
  • workflow layer: doula-approval-workflow.ts
  • current behavior:
    • promotes approved applicants in TBC Doula Database to Officially Onboarded
    • stores canonical approval and mentorship metadata in Notes
    • updates mentor roster labels in Assigned Mentor/Mentees
    • creates, updates, or removes the linked Provider Directory record based on admin visibility choice
    • powers /admin/doula-applications/[id], /admin/doulas, /admin/mentors, and /doula/mentor

Interview scheduling

  • shared Airtable path: route.ts, route.ts, interviews.ts
  • booking write path: doula-profile-page.tsx
  • current behavior: writes booked interviews into Interview Status through Airtable-backed /api/appointments

Doula scheduling availability

  • availability write path: route.ts
  • current behavior: persists Interview Availability JSON and Interview Time Off JSON directly on the canonical doula record in TBC Doula Database

Recommended Airtable Scope For Tomorrow

Keep / confirm existing source tables

  • Parents base:
    • Parent Intake Forms
    • Parent-Doula Matches
    • Active Contracts
    • Parents Payments
    • Interview Status
  • Doulas base:
    • TBC Doula Database
    • Provider Directory
  • Marketing base:
    • Blog Posts
    • Newsletter Signups
  • Admin base:
    • Admin Payments

Add only the missing tables required by current app behavior

  1. Invoices
  2. Doula Availability
  3. Time Off

Why The Current Matching Table Is Likely Enough

The current live Airtable base already has Parent-Doula Matches, which is materially better than the older generic schema assumptions.

What it already gives us:

  • parent intake link
  • doula identity fields
  • match date
  • match status
  • source of match
  • notes
  • contract link
  • interview link

What still needs to be verified or added for app parity:

  • explicit doula availability response semantics
  • requested-doula-unavailable tracking
  • response timestamps
  • visibility-to-client rules, if needed

Recommendation:

  • do not create a new match table unless Parent-Doula Matches proves insufficient at the field level
  • prefer extending Parent-Doula Matches over introducing a duplicate domain table
  • current app implementation still stores structured app metadata in Notes under a TBC_MATCH_META prefix, but the live table now also has first-class response fields for cleaner Airtable-side reporting and dedupe

Field Mapping: Parent Intake Form -> Parent Intake Forms

Marketing form fieldCurrent local keyAirtable field to target tomorrowNotes
Birthing Person's First NamefirstNameFirst Namealready implied by current mapper
Birthing Person's Last NamelastNameLast Namealready implied by current mapper
EmailemailEmailalready implied by current mapper
PhonecountryCode + phonePhonestore as a normalized combined number
Estimated Due DateestimatedDueDateEstimated Due Datealready implied by current mapper
CitycityAddress or Citycurrent code uses Address; confirm which field the existing base actually uses
Delivery Hospital NamedeliveryHospitalNameDelivery Locationcurrent code references Delivery Location with a trailing space; normalize this tomorrow if possible
Birth HistorybirthHistoryBirth Historynew field likely needed
Type of supportsupportTypeBirth/Postpartumcurrent code already expects this field name
Specific doula interestdoulaInterestInterested In Specific Doula(s) Or Would Like To Connect With Any Available Doula(s)? Please Specify *current code already expects this long field name
Insurance coverageinsuranceCoverageCovered By Insurance?current code already expects this field name
Kaiser benefit flaguseKaiserBenefitKaiser Benefit?current code already expects this field name
Out-of-pocket flexibilityoutOfPocketFlexibilityOut Of Pocket Flexibilitynew field likely needed
Specific budgetspecificBudgetSpecific budget?current code expects Specific budget? with a trailing space; normalize if possible
Vision of supportvisionOfSupportWhat Is Your Vision For Birth/Birth Supportcurrent code already expects this field name
How heard about TBChowHeardHow Did You Hear About Us?current code already expects this field name
Referral source detailreferralSourceReferral Sourcenew field likely needed
Submission timestampderivedSubmission Datecan be created time or written explicitly
Needs consultationderivedNeeds Consultationcurrent local rule: true when specific doula interest is blank
Workflow statusderived/adminClient Statusset by admin workflow or automation, not by public form

Field Mapping: Doula Application -> TBC Doula Database

Marketing form fieldCurrent local keyAirtable field to target tomorrowNotes
First NamefirstNameDoula First Namealready implied by current mapper
Last NamelastNameDoula Last Namealready implied by current mapper
EmailemailEmailalready implied by current mapper
Areas servedareasServedAreas Servedalready implied by current mapper
Type of Doula SupporttypeOfSupportType of Doula Supportalready implied by current mapper
Years of experienceyearsOfExperienceYears of Experiencealready implied by current mapper
Other services offeredotherServicesOther Services Offeredalready implied by current mapper
How did you hear about us?howHeardHow Did You Hear About Us?likely needs to be added or confirmed
Formal training / certificationeducationHistoryFormal Training / Certificationnew field likely needed unless there is already an equivalent
Tell us more about yourselfaboutYourselfBackgroundcurrent code already maps Background onto doula bio
Application statusderivedApplication Statusshould default to something like Submitted or New Application

Important Doula Application Gap

Tomorrow should not blindly reuse the current generic createDoula() path without checking it first.

Why:

  • airtable.ts currently writes only a partial doula profile shape
  • it does not currently write all of the new public application fields

Recommended fix:

  1. add a dedicated createDoulaApplicationRecord() mapper, or
  2. extend doulaToAirtable() so it fully supports the public application payload

Option 1 is cleaner for tomorrow.

Recommended Current Interview Table: Interview Status

Use the live Interview Status table as the baseline. TBC calls these Interviews, even though the current app type is still Appointment.

Field NameTypeNotes
Parent-Doula MatchLinkalready exists live
Interview TypeSingle selectalready exists live
Interview Date/TimeDate timealready exists live
Interview StatusSingle selectalready exists live
Parent Interview FeedbackLong textalready exists live
Doula Interview FeedbackLong textalready exists live
Interview OutcomeSingle selectalready exists live
NotesLong textalready exists live
Next Steps (AI)AI textalready exists live

Likely additions still needed for app parity:

  • Google event ID
  • meeting link
  • cancel reason
  • confirmed at / completed at / cancelled at

Automation Ownership

Airtable should own

  • parent intake confirmation / account-invite email
  • doula application confirmation / account-invite email
  • requested-doula-unavailable branch marker in Parent-Doula Matches

App should own

  • form validation
  • writing records into Airtable
  • reading records back into portal pages
  • doula availability response actions
  • current requested-doula-unavailable email send path until a dedicated Airtable automation replaces it
  • client-side success/error states
  • interview booking creation

Later integrations

  • Google Calendar event creation
  • Google Meet link insertion
  • any webhook-based sync between Airtable and external systems

Confirmed automation inventory and risk

Parent Database active automations

  • Parent Sign Up Created
  • Postpartum Check-In!
  • First Birthday Email
  • Final Payment Reminder
  • Email response to referral form
  • Parent - Hired to Contract
  • New Contracts to Bookkeeping Spreadsheet
  • Post to Availability
  • Closed Contracts

Confirmed trigger detail:

  • Parent Sign Up Created
    • when a record is created in Parent Intake Forms
    • sends email
    • branches on Kaiser Benefit?

Operational consequence:

  • a real parent-intake write can trigger Gmail, Slack, Google Sheets, and downstream workflow actions

Doula Database active automations

  • Directory Doula Confirmation Email With Payment Link
  • [TBC Doula Database] Send Webhook when Record is Updated
  • [Doula Directory] Send Webhook when Record is Created
  • [TBC Doula Database] Send Webhook when Record is Created copy

Inactive:

  • New Doula Sign Up Email Confirmation With Doula Profile Form
  • Update Record via Form V2
  • [Join The Team Form Submission] ...
  • Yurii

Operational consequence:

  • doula writes can trigger webhook side effects immediately

Family Favorites active automations

  • Send Webhook [Record Updated]
  • Send Webhook [Record Created]

Marketing

No automation inventory confirmed yet.

Payments

  • old Payments base is deleted
  • any screenshot of that base should be treated as stale
  • current finance-op base is TBC Admin Database
  • Parent Database contains Parents Payments
  • canonical model:
    • Active Contracts = canonical contract-economics record once PandaDoc metadata is ingested
    • Parents Payments = canonical external money-in ledger
    • Admin Payments = canonical internal contract-level finance and payout ledger
  • relationship model:
    • one active contract has many parent payment receipts
    • one active contract has one admin finance ledger row
  • business rules:
    • PandaDoc creates and sends contracts to parents
    • TBC collects 50% of the contract value upfront when the contract is signed
    • 100% of the contract payment is collected by TBC
    • TBC pays itself the referral fee from the full contract payment, then pays the doula
    • birth-contract referral fees range from 10% to 20% depending on doula seniority and whether TBC handles Kaiser billing
  • field ownership:
    • Active Contracts: total contract value, deposit due, balance due, referral fee percent, referral fee amount, doula payout obligation, Kaiser handling, PandaDoc reference
    • Parents Payments: contract, payment stage, gross amount received, payment method, paid date, receipt status, external reference
    • Admin Payments: contract, total received to date, remaining due, referral fee captured, doula payout due, payout status, payout method, bookkeeping notes

Recommended Tomorrow Implementation Order

  1. Run one controlled live validation for the parent intake write path
  2. Run one controlled live validation for the public doula application write path
  3. Decide whether Admin Payments should keep structured Notes metadata or gain first-class payout fields
  4. Activate the existing PandaDoc send/status/webhook scaffold with live credentials and webhook registration
  5. Add Google Calendar / Meet sync once production interview persistence is stable

Safe test procedure

Before any live production-base write:

  1. confirm whether the relevant automations are enabled
  2. if enabled, choose one:
    • disable them temporarily
    • use a sandbox copy
    • accept the side effects explicitly
  3. use one clearly labeled test record only
  4. do not run any delete/cleanup operation without explicit approval

Remaining Code Tasks

Parent intake

  • complete one controlled live submit validation against production Airtable
  • confirm downstream email and automation behavior

Doula application

  • complete one controlled live submit validation against production Airtable
  • confirm webhook side effects and downstream email behavior

Doula approval workflow

  • confirm that the approved-doula metadata stored in Notes is acceptable long-term or replace it with first-class Airtable fields
  • confirm that Provider Directory rows created from approved doulas match the intended public listing format
  • confirm mentor roster labels in Assigned Mentor/Mentees are enough for ops visibility

Match responses

  • monitor whether Parent-Doula Matches can fully stop depending on structured Notes metadata now that first-class response fields exist

Interviews

  • verify that Interview Status supports the production interview workflow without additional schema changes

Payments and invoices

  • /api/invoices and the doula invoice creation/detail routes are now Airtable-backed through the Invoices table in TBC Admin Database
  • WORK-293 is complete: signed webhook reconciliation now uses deterministic idempotency keys and creates contract-linked receipt records exactly once
  • decide whether Admin Payments should gain first-class payout fields instead of relying on structured Notes

Remaining Questions

  1. Are the current Airtable automations already attached to:
    • Parent Intake Forms
    • TBC Doula Database or do they use different source tables?
  2. Does the parent intake base already have fields for:
    • birth history
    • out-of-pocket flexibility
    • referral source
    • needs consultation
  3. Does the canonical doula destination already have fields for:
    • how heard
    • training/certification answer
    • application status default
  4. What additional interview fields are needed beyond the current Interview Status table?
  5. Should Admin Payments stay metadata-driven in Notes or gain first-class payout fields?
  6. Which PandaDoc template ids should map to Birth, Postpartum, and Extended contract packages in production?

Next Call Checklist

  • Open the Parents base
  • Open the Doulas base
  • Open the TBC Admin base
  • Review the existing automations together
  • Confirm exact table names used by those automations
  • Confirm exact field names used by those automations
  • Confirm live create-trigger and webhook side effects before any production write validation
  • Decide whether parent-intake live testing will use sandbox, disabled automations, or accepted side effects
  • Test one real parent intake submission end to end only after the testing mode is approved
  • Test one real doula application end to end
  • Define the invoice table contract
  • Wire /api/invoices and the invoice surfaces
  • Decide whether Admin Payments needs first-class payout fields
  • Re-test /parent-intake-form, /doula-sign-up, /doula/leads, /client/matches, /client/search/d1, /client/appointments, /doula/calendar
  • Re-test /client/payments, /admin/payments, /doula/invoices

Bottom Line

The Airtable cutover is now in place for intake, doula applications, matching, interviews, and payment ledgers.

The next phase is narrower:

  • validate the two public write paths safely in production
  • refine invoice approval and payout operations
  • activate the PandaDoc scaffold with live credentials, webhook registration, and one controlled send test