Use the following API endpoints to configure advanced settings of your online forms via the API Console.

The ID of a form is the alphanumeric string in its FormSmarts.com URL. For example, if a form's URL is https://formsmarts.com/form/xyz, its Form ID is xyz.

Notification Email Subject Line

To retrieve the current email subject line for a from, insert the form's ID into the URL and submit a GET request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/email_subject
HTTP Method
GET

To customize the subject line of the notification email, insert the form's ID into the URL and submit a PUT request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/email_subject
HTTP Method
PUT
ParameterDescriptionNotes
template The email subject template. May contain placeholders $form_name, $form_id, $fs_ref_num, $1, $2,… $n. Required

Submit a DELETE request to cancel the customized email subject line and revert to the default one.

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/email_subject
HTTP Method
DELETE

Form Prefill

To get the prefill settings of a form, insert the form's ID into the URL and submit a GET request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/prefill
HTTP Method
GET

To allow or prohibit prepopulated forms that are not signed, insert the form's ID into the URL and submit a PUT request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/prefill
HTTP Method
PUT
ParameterDescriptionNotes
allow_unsigned yes (allowed) or no (prohibited) Required. Unsigned form prefill is not allowed by default.

Pre-Filled URL

In addition to the generic FormSmarts.com and f8s.co form URLs, FormSmarts members can create pre-filled URLs that include the data needed to pre-populate some of the input fields of an online form. This is useful to pre-fill the ID or email identifying a customer or the amount due on a payment form, as well in many other contexts.

To generate a pre-filled URL for a form, log in to the API Console, paste the API Endpoint listed below after inserting your form's ID into it, and submit a POST request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/prefilled_url
HTTP Method
POST
ParameterDescriptionNotes
pf_f1, pf_f2, … pf_f10 The value you want to pre-populate the corresponding input field with. For example, pf_f1=Jane Doe will pre-fill the first input field of the form with the value Jane Doe. "pf_f1" stands for "pre-fill field 1". You can get a list of the prefill parameter name for each field of a form with the API.
pf_ro1, pf_ro2, … pf_ro10 Makes an input field read-only. For example, pf_ro3=1 makes the third input field read-only, preventing users of the form from modifying its value. "pf_ro1" stands for "pre-fill read-only 1".

Save & Resume

To review the Save & Resume configuration a form, log in to the API Console and submit a GET request with the information below. Replace Form_ID in the API Endpoint with the ID of your form.

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/save_resume
HTTP Method
GET

To enable Save & Resume and allow users to save a form and continue at a later time, use the API Endpoint URL listed below (after inserting your form's ID into it) and submit a PUT request.

To disable Save & Resume, set enabled = no.

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/save_resume
HTTP Method
PUT
ParameterDescriptionNotes
enabled Set to yes to allow users to start filling the form out and continue later, set to no to disable this feature. Optional, defaults to "yes" if parameter is omitted.
ttl Number of days the originator of a form entry can edit it before the form times out. Optional, parameter defaults to 15 if left out. Maximum value: 30. TTL stands for "time to live".
shared_ttl Number of days someone with whom a form entry was shared can edit it. Set to 0 to disable sharing. Optional, parameter defaults to 0 (no sharing) if omitted.
passcode Set to yes to protect access to the form entry with an auto-generated passcode (recommended), set to no to allow access without a passcode. Optional, defaults to yes (passcode required, recommended) if left out.
shared_can_submit Set to yes to allow someone with whom a draft form entry was shared to submit the form. If set to no, the person will be able to modify the form and save their changes, but won't be able to submit it. Optional, defaults to yes if omitted.

To disable Save & Resume and delete the form's Save & Resume configuration, submit a DELETE request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/save_resume
HTTP Method
DELETE

Private Form

Private Forms allow FormSmarts members to limit who can to submit a form to invited users within their account.

To check whether a form is private, insert its ID into the API endpoint URL below and submit a GET request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/privacy
HTTP Method
GET

Forms are public by default. To make a form private, insert its ID into the URL below and submit a PUT request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/privacy
HTTP Method
PUT

To make a Private Form public, insert its ID into the URL below and submit a DELETE request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/privacy
HTTP Method
DELETE

Form Confirmation Emails (Auto-Responder)

FormSmarts auto-responder allows you to send an automatic email confirmation when someone submits one of your forms. Note: You can also toggle the autoresponder on and off with the form builder.

To check whether the confirmation email is enabled for a form, insert its ID into the API endpoint URL below and submit a GET request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/autoresponder
HTTP Method
GET

To send a confirmation email to the respondent after form submission, insert the ID of the form into the URL below and submit a PUT request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/autoresponder
HTTP Method
PUT
ParameterDescriptionNotes
mode default: send a copy of the form submission with the auto response email
no_data: don't provide a copy of the form response in the confirmation email
Optional

To disable the email autoresponder and stop sending a copy of the form response to the user, insert the form's ID into the URL below and submit a DELETE request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/autoresponder
HTTP Method
DELETE

Calendar Event

If you add information about an event (date, time, location, organizer info) to a registration form, FormSmarts will attach a calendar event to payment confirmation emails, auto-responder messages, and the email confirmation respondents can request on the Summary page of a form.

To list details of the calendar event associated with a form, insert the form's ID into the URL below and submit a GET request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/event
HTTP Method
GET

To associate an event with a form, insert its ID into the URL below and submit a PUT request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/event
HTTP Method
PUT
ParameterDescriptionNotes
start Start date and time of the event Required. ISO date format.
location Event location (or URL for a webinar) Required
organizer_email An email address Required. Address must be associated with your FromSmarts account.
organizer_name Optional
title Title of the event. Optional. If not specified, the form title is used.
end End date and time of the event Optional. ISO date format.
timezone Timezone of the event as listed here, e.g. America/Los_Angeles Optional. If unspecified, the timezone of your account is used.

To remove the event associated with a form, insert the form's ID into the URL below and submit a DELETE request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/event
HTTP Method
DELETE

S/MIME Certificate Addition Request

FormSmarts' secure encrypted email requires that we hold a valid, up-to-date S/MIME certificate for each destination email address of a form.

To add a S/MIME certificate to your account:

  1. Submit a Certificate Addition Request (CAR) to the API Endpoint below via the API Console
  2. Send a signed message to the long email address like cert+yBf4LjgsqmoOtK0vzJ7sqYLKO2iMNvj-vyEVXE3F2aM@formsmarts.com shown in the response of the Certificate Addition Request

Please make sure the email message is digitally signed with the S/MIME certificate you would like to add to your account.

API Endpoint
https://formsmarts.com/api/v1/certificates
HTTP Method
POST
ParameterDescriptionNotes
email The email address associated with the S/MIME certificate you would like to add to FormSmarts. Required. The email address must already be registered in your account and verified.

Enable/Disable a Form at a Scheduled Date

You can easily enable or disable a form on a scheduled date and time with the form builder.

This API is provided to allow recurring schedules needed to support uses like enable the expenses claim form between noon and 5pm on the last day of each month.

To find out the details of a scheduled form status change, insert its Job ID into the API endpoint URL below and submit a GET request:

API Endpoint
https://formsmarts.com/api/v1/jobs/Job_ID
HTTP Method
GET

To list all scheduled jobs associated with a form and find out their Job ID, replace FORM_ID in the URL below with the form's ID and submit a GET request:

API Endpoint
https://formsmarts.com/api/v1/forms/FORM_ID/jobs?event_names=["FormStatusChange"]&types=["cron"]
HTTP Method
GET

Submit a POST request to schedule a form status change.

The hour, day, month and day_of_week parameters are concatenated to generate a Cron expression. The syntax and semantics of each parameter are the same as in a standard cron expression.

API Endpoint
https://formsmarts.com/api/v1/jobs
HTTP Method
POST
ParameterDescriptionNotes
event_name Enter value FormStatusChange
context {"form_id": "Form_ID", "enabled": false} Specify the ID of the form and whether you want to enable ("enabled": true) or disable it ("enabled": false).
timezone The timezone of the hours, day of the month, month and day of the week specified as a timezone name.
hour A number 0–23, allowed special characters: *, , and -. Optional, parameter defaults to * (every hour) if omitted.
day Day of the month 1–31, allowed special characters: *, ,, - and L (last day of the month). Optional, parameter defaults to * (every day) if omitted.
month Month 1–31, allowed special characters: *, , and -. Optional, parameter defaults to * (every month) if omitted.
day_of_week Day of the week 0–6 or Sun–Sat, allowed special characters: *, , and -. Optional, parameter defaults to * (every day of the week) if omitted.
enabled Set to no to suspend the form status change scheduled job, set to yes to restore it. Optional, defaults to yes if parameter is omitted.

To cancel the scheduled form enabled/disabled status change, insert the Job ID into the URL below and submit a DELETE request:

API Endpoint
https://formsmarts.com/api/v1/jobs/Job_ID
HTTP Method
DELETE

Discount Codes

The Discount Code API allows you to manage the discount codes associated with one of your payment forms. This video shows how to use the API.

To list the discount codes associated with an online payment form, insert the ID of the form into the URL (API endpoint) and submit a GET request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/discounts
HTTP Method
GET

To create a discount code and associate it with a payment form, insert the form's ID into the URL and submit a POST request. You can offer a discount based on a percentage or a flat monetary value.

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/discounts
HTTP Method
POST
ParameterDescriptionNotes
code The discount code, for example: FSCP-FALL-REG-AG73PB. Discount codes must start with FSCP- (FSCP stands for FormSmarts CouPon). Required
percentage The discount percentage, for example: 20 to offer a 20% discount. You must provide a value for either the percentage or amount parameter. Optional
amount The amount of the flat discount, for example: 15.65 to offer a $15.65 discount. Optional
code_field_name The name of the input field where users are to enter the discount code on the payment form, for example: Discount Code. This is used to identify the input field on the form, so the value submitted must be exactly the same as the field question on the form. If code_field_name is not specified, the discount code can only be used by passing it to the fs_ctxval parameter of the form's URL. Optional
start_date The activation date of the discount code1. The discount code starts to be valid immediately if start_date is omitted.

Specify the activation date and time in ISO 8601 format, e.g. 2020-12-30 15:00:00 in the timezone of your account.

Optional
end_date The date and time after which the discount code is no longer valid1. The promo code is open ended if end_date is omitted.

Enter the end date and time in ISO 8601 format, e.g. 2021-12-03 15:00:00 in the timezone of your account.

Create a discount code with an end date to offer an early bird discount on a form.

Optional

To delete one or all discount codes associated with a payment form:

  1. Insert the ID of the form into the API endpoint
  2. Pass the discount code to delete to the code URL parameter, i.e. code=FSPI-The-Discount-Code
  3. Submit a DELETE request
API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/discounts?code=FSPI-The-Discount-Code
HTTP Method
DELETE
ParameterDescriptionNotes
code The discount code to delete, for example: FSPI-The-Discount-Code.

If the code parameter is omitted, all discount codes associated with the form will be deleted.

Optional

Webhooks

The API to register a webhook URL, update it and cancel a webhook is discussed in the webhook documentation:

PayPal Payment Receiver

With PayPal integration, payments are sent by default to the PayPal account matching your FormSmarts login email (which must be the same as your Primary PayPal). Some types of FormSmarts accounts also allow you to customize the PayPal payment receiver on a form by form basis.

To check the payment receiver (PayPal account) associated with a form, insert its ID into the API endpoint URL below and submit a GET request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/payment_receiver
HTTP Method
GET

To update the payment receiver (PayPal account) associated with a form, insert the ID of the form into the URL below and submit a PUT request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/payment_receiver
HTTP Method
PUT
ParameterDescriptionNotes
receiver_email The PRIMARY email address of the PayPal account you want to associate with the form. The address must already be registered and verified in your FormSmarts account. Required

To stop sending payments associated with a form to a customized payment (PayPal) receiver and revert to the PayPal account under your FormSmarts account's login email, insert the form's ID into the URL below and submit a DELETE request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/payment_receiver
HTTP Method
DELETE

Forms Metadata

To get the ID, name, date last used, associated emails, data storage status and URL of each of your online forms, submit a GET request:

API Endpoint
https://formsmarts.com/api/v1/forms
HTTP Method
GET

Note: the last_used timestamps returned are UTC.

Input Fields

To get a list of the input fields of an online form in the order they appear on the form, and the corresponding pre-fill parameter names, insert the ID of the form into the URL (API endpoint) and submit a GET request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/fields
HTTP Method
GET

Form Colors

To check the current buttons and links colors of a from, insert the form's ID into the URL and submit a GET request:

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/colors
HTTP Method
GET

To customize the color of a form's buttons and links, insert the form's ID into the URL and submit a PUT request. Note: You can also change colors directly with the form builder.

API Endpoint
https://formsmarts.com/api/v1/forms/Form_ID/colors
HTTP Method
PUT
ParameterDescriptionNotes
button_color The lowercase 6-character hexadecimal code of the color, e.g. ff8215. Required. To revert to the default button color, enter an empty color code.
link_color The lowercase 6-character hexadecimal code of the color, e.g. ff8215. Required. To revert to the default link color, enter an empty color code.

Errors

Error 400 - Bad Request

Your request was not processed because some parameters are missing or invalid. Check the documentation for the resource you are trying to access.

Error 401 - Authentication Failed

You're not signed in to FormSmarts or are using an incorrect FormSmarts account number and API key to authenticate the request.

Error 403 - Forbidden

You are trying to access a resource which is not yours. You're probably signed in to the wrong FormSmarts account or are using the wrong FormSmarts account number and API key to authenticate the request.

Error 404 - Resource Not Found

No resource was found at this URL (endpoint) you specified.

Error 405 - Method Not Allowed

The HTTP request method (POST, GET, PUT or DELETE) you're using to access a resource is not supported by this resource. For example, you might be trying to create (POST) a resource that can only be modified (PUT).

Error 500 - Internal Server Error

There is a problem with our systems. If the issue persists, please let us know.

Error 409 - Conflict

An action you were trying to perform couldn't be completed because of a conflicting update from someone else logged in to your account or another session.

Error 503 - Service Not Available

The service you're trying to use is temporarily unavailable. Check the Status Page for more information.
  1. Discount code validity dates options are not available with Starter accounts.