🎉 Celebrate with 10% OFF on All Products! Use Code: GFEX10 Or Buy Any 2+ Items for 30% OFF with Code: GFEX30!

Gravity Forms Teachworks Integration Setup Guide

Updated 7 min read Gravity Forms Integrations A–Z
On this page
  1. Step 1: Install and License the Add-on
  2. Step 2: Connect Your Teachworks Account
  3. Generate an API token
  4. Save and test the token
  5. Step 3: Create a Teachworks Feed
  6. Family or independent student
  7. Status, duplicates and notes
  8. Students
  9. Enquiry details
  10. Field Mapping Reference
  11. Conditional Logic and Rate Limits
  12. Developer Filters
  13. Checking Delivery on the Entry Screen
  14. Partly sent entries and resending
  15. Troubleshooting & FAQ
  16. An enquiry did not reach Teachworks. What happens?
  17. The token is rejected.
  18. The note says a first and a last name are required.
  19. A subject or custom field was not set.
  20. The students were not added to the family.
  21. Resource Hub

Parents often contact several tutoring centers at once, and the one that calls back first usually wins the family. The Gravity Forms Teachworks Premium Add-on sends every enquiry from your website to Teachworks: the parent becomes a prospective family with up to three children as students, or an adult learner becomes an independent student. Grades, schools, birth dates, subjects and the enquiry details are filled in for you.

Existing customers are found by email, so families are never duplicated. This guide covers the API token, the feed settings, delivery checks and resending.

System Requirements & Prerequisites

  • WordPress: Version 6.5 or higher
  • PHP: Version 7.4 or higher
  • Gravity Forms: Version 2.5 or higher
  • Teachworks account: A Growth or Premium subscription (API access is only available on these plans) with the API add-on switched on
  • GravityExtra license: The Teachworks add-on installed, activated and licensed with an active GravityExtra license key

Step 1: Install and License the Add-on

  1. Go to Plugins → Add New → Upload Plugin, upload the add-on ZIP file and click Activate.
  2. Open Forms → Settings → Teachworks.
  3. Enter your license key in the Gravity Extra License section and save. The Teachworks API settings appear once the license is active.

Step 2: Connect Your Teachworks Account

Generate an API token

  1. In Teachworks click Account → Integrations & Add-ons and search for “API”.
  2. Switch the API add-on on, open its Settings and click Generate API Token.
  3. To try the integration first, click Create Sandbox Account on the same screen and use the sandbox token instead.

Save and test the token

Paste the token into API Token and click Save Settings. The add-on tests it with a read-only request; nothing is created in Teachworks. On success you see Connected to Teachworks. A token that Teachworks rejects is not saved and the reason appears under the field. A network problem does not block saving. Test connection checks again and refreshes the locations, teachers, services and subjects used in the feed.

Backup email for failed enquiries defaults to the site admin email. Leave it empty to turn it off.

Teachworks API settings in Gravity Forms with a connected API token, the Test connection button and the backup email
Forms → Settings → Teachworks with a connected API token.

Step 3: Create a Teachworks Feed

Open your enquiry form, go to Settings → Teachworks and click Add New. The button is available once an API token is saved.

Family or independent student

  • Family (parent + children): the person filling in the form is the customer, and each student in the Students section is added as a child student. Empty students are skipped.
  • Independent Student: for adult learners who are billed directly. The customer is also the student, and the Student 1 birth date, grade, school and subjects fill their student profile. Students 2 and 3 are not used.

Map First Name + Last Name, or one Full Name field (split at the last space). Teachworks requires both a first and a last name. Map email, mobile, home and work phone as needed.

Teachworks feed with feed name, Create as Family or Independent Student, and the parent name, email and phone mapping
A Family feed with the parent mapped as the customer.

Status, duplicates and notes

  • Customer Address: street, line 2, city, state, ZIP and country, sent as entered.
  • Status: Prospective (default), Active or Inactive for new customers and students. Existing customers keep their status.
  • Reuse the existing customer with the same email (on by default): an exact email match, ignoring case, is reused, and only students whose first and last name are not already in the family are added. Without an email, a new customer is always created.
  • Add the enquiry to the existing customer’s notes (on by default): the new enquiry is added below the current notes, never replacing them.
  • Mark new profiles as “New” in Teachworks (on by default).
  • Customer Custom Fields: needs the Teachworks Custom Profile Fields add-on. Type the custom field name exactly as it appears in Teachworks, or its numeric field ID. For select menus the value must match one of your options.
Teachworks feed status, reuse and notes options and customer custom fields
Status, the duplicate and notes options and a customer custom field.

Students

Each of the three students has First Name, Last Name, Full Name, Birth Date, Grade, School and Subjects / Instruments. If only a first name is given, the customer’s last name is used. Birth dates are sent as YYYY-MM-DD; a date that cannot be read is kept in the student notes. Subjects (one value or a comma-separated list, such as checkbox answers) are matched to your Teachworks subjects by name and are also written to the student notes, so unmatched answers are not lost.

Teachworks feed Student 1 mapping with first and last name, birth date, grade, school and subjects
Student 1 mapping; Students 2 and 3 have the same settings.

Default Location, Default Teacher (active employees) and Default Service are optional and apply to every new student. Student Custom Fields work like the customer custom fields and are applied to every student created from the entry.

Teachworks feed default location, default teacher, default service and student custom fields
Defaults for new students and a student custom field.

Enquiry details

Map Subject / Instrument Interest, Level / Experience, Availability, How They Heard About You and Message. They are written to the customer notes as lines such as “Availability: Weekdays after 4 pm”, followed by the student names, the message and the form name and entry number.

Teachworks Enquiry Details mapping with interest, level, availability, how they heard about you, message and conditional logic
Enquiry Details from the Free Assessment form.

Field Mapping Reference

Feed setting Teachworks field How it is sent
First + Last Name / Full Name Customer first_name, last_name Both required
Email, Mobile, Home, Work Phone email, mobile_phone, home_phone, work_phone Email is also used to find existing customers
Customer Address address, address_2, city, state, zip, country As entered
Status status New customers and students only
Enquiry fields + Message Customer additional_notes Added below existing notes when reused
Student name, Grade, School Student first_name, last_name, grade, school Up to three child students
Student Birth Date birth_date YYYY-MM-DD
Subjects / Instruments standard_subject_ids + student notes Matched by subject name
Default Location, Teacher, Service default_location_id, default_teacher_ids, default_service_ids New students only
Custom fields Custom profile fields Matched by name or field ID

Conditional Logic and Rate Limits

Enable Conditional Logic and choose Only send when conditions are met. For example, send “Who are the lessons for?” = “My child” to a Family feed and “Myself” to an Independent Student feed on the same form.

Teachworks allows 4 API requests per second per token. The add-on spaces its own requests and retries once after a short wait when Teachworks answers that the limit was reached.

Developer Filters

The gravityextra_teachworks_payload filter receives $payload (with the keys type, customer, students, enquiry_notes, customer_custom and student_custom), $feed, $entry and $form, and must return the payload. A second filter, gravityextra_teachworks_api_base, changes the API base URL. This example gives new students the online location when the visitor chose online sessions in field 21 of form 4:

functions.php
PHP
// Online sessions: use the online location for new students
add_filter( 'gravityextra_teachworks_payload', function( $payload, $feed, $entry, $form ) {
    if ( (int) $form['id'] !== 4 || rgar( $entry, '21' ) !== 'Online' ) {
        return $payload;
    }
    foreach ( $payload['students'] as $i => $student ) {
        $payload['students'][ $i ]['default_location_id'] = 14;
    }
    return $payload;
}, 10, 4 );

Checking Delivery on the Entry Screen

Entries from a form with an active feed show a Teachworks box with the status (Sent, Partly sent, Not delivered or Not sent), the Customer ID (marked “existing customer” when reused) and the new Student IDs. The status and customer ID are also available as entry list columns and in exports.

Teachworks status box showing Sent with the new family customer ID, two student IDs and the Send again anyway button
A new family with two child students.

Resending a delivered entry starts over. Once an entry is Sent, the box shows a notice and Send again anyway, and you are asked to confirm. The customer is looked up by email again and only students who are not in the family yet are added; an entry without an email creates a second customer.

When a returning parent enquires about another child, the entry note shows what happened:

Entry note confirming the existing Teachworks family was found by email, one new student was added and one was already in the family
An existing family found by email: one new student added, one already in the family.

Partly sent entries and resending

The customer, notes, students and custom fields are sent one after another, and every finished step is saved on the entry. If the customer is saved but a later step fails, the entry becomes Partly sent. Click Send to Teachworks again (available to users who can edit entries): only the missing steps are sent and the customer is not created twice. The button also appears on Not delivered entries and reruns every active Teachworks feed whose conditions match.

Teachworks status box showing Partly sent with the saved customer ID and the Send to Teachworks again button
The family is saved; the second student is still missing.
Entry notes showing the student that could not be added, then the resend that added only the missing student to the saved family
A timed-out request, then a resend that added only the missing student.

Troubleshooting & FAQ

An enquiry did not reach Teachworks. What happens?

The entry is kept and marked Not delivered or Partly sent, a note explains why, and the backup email “Teachworks enquiry not delivered — [form name]” lists the customer and student details with a link to the entry. The API token is never included. Fix the cause and click Send to Teachworks again.

The token is rejected.

Teachworks answers with HTTP 401 when the token is wrong or the plan does not include the API. Check that you are on Growth or Premium, generate a new token if needed, save it and resend the affected entries.

The note says a first and a last name are required.

Map First + Last Name, or a Full Name field that contains both, and make the field required. Nothing is sent until the name is complete; resend the entry afterwards.

A subject or custom field was not set.

Subjects must match a Teachworks subject name (case does not matter); unmatched answers stay in the student notes. A custom field name that is not found is reported in the entry note. Check the spelling, or use the numeric field ID.

The students were not added to the family.

The email belongs to an independent student in Teachworks, so children cannot be added to that record. The entry note says so; add the students by hand or use a different email. Forms → Settings → Logging gives a detailed trace.

Resource Hub

Still need help?

Our support team answers tickets every day, usually within a few hours.

0
0
Your Cart
Your cart is emptyReturn to Shop
🔥 FREQUENTLY BOUGHT TOGETHER
Complete Combo & Save 40%!
ITEM IN YOUR CART
Gravity Forms Klaviyo Add-on
$39.00/yr
+
🎁 RECOMMENDED ADD-ON SAVE 40% OFF
Original Price: $39.00/yr
Bundle Special Price: $23.40/yr