Sessions allow you to prepare a form for a user and pre-fill it with information. The signer completes the form, signs, and then is returned to your website if you set a success URL (otherwise they will see a default success page hosted by Nextform with a PDF of the completed form). The form data can be returned to your website with a webhook or obtained later with an API request.
The body should be posted as raw JSON. Specify a formType if you know what type of form you need from your contact. If you do not specify a form type, Nextform will present your contact with a short questionnaire which will direct them to the correct form. This is helpful in situations where you do not know if your contact is a U.S. citizen or where they reside.
There are several ways to authenticate your request, read our authentication guide to learn more.
POST https://api.nextform.app/sessions
{
"formType": "w9Oct2018"
}The endpoint responds with a session object. The url property is a link to the form page hosted by Nextform. If you have set up your business name and logo, that information will appear at the top of the form.
{
"id": "qfofUrdgVoKLmHMHYwkq9yHAdgQVZ5Dc",
"reference": null,
"status": "open",
"url": "https://nextform.app/form/w9Oct2018...",
"successUrl": null,
"signerEmail": "user@example.com",
"expiresAt": null,
"expirationMessage": null,
"formType": "w9Oct2018",
"formData": null
}As you may have noticed in the object above, there are other optional session properties that may be set. Setting these properties can enhance your integration, reduce the amount of time it takes for your user to complete the form, and improve the quality of form input. The post request below uses all settable session properties.
POST https://api.nextform.app/sessions
{
"reference": "ab0b12e2-979c-47be-97d8-acf614685d57",
"successUrl": "https://example.com/thank-you",
"signerEmail": "user@example.com",
"expiresAt": "2024-07-21",
"expirationMessage": "This session has expired.",
"formType": "w9Oct2018",
"formData": {
"name": "Robert Smith"
}
}If you would like to attach a user ID or other unique identifier to the session, you may set a string up to 255 characters in length. The reference property will be copied over to the form object and the signature object associated with the session, and it will be returned when a webhook is delivered. It may also be queried via our list forms endpoint.
If you would like to send your users to a custom redirect page upon completion of the form, include a valid URL as a string. If you do not provide a success URL, users will see a default thank-you page hosted by Nextform where they can review and download a PDF of the completed form.
The email address to associate with the individual completing and signing the form. We recommend setting this property if you have a verified email address for your user. The email address gets carried over to the signature object associated with the form so that the signature is properly attributed.
The desired type of form as a string. Allowed values include auto, w9Oct2018, w8benOct2021, or w8beneOct2021. If you do not specify a formType, it will default to auto, in which case your contact will be presented with a brief questionnaire that will direct them to the appropriate form based on their answers. The session will be updated appropriately when your contact completes the questionnaire. For more information, visit the Available Forms page.
The brandId is a unique identifier for a brand. If you have a Enterprise Plan subscription, you can create multiple brands, each with its own logo and company name. When you request a form, you can specify the brand, or use your default brand. This enables you to create a many-to-many service where multiple users of your service can to set their own brands and request tax forms from their own parties. For more information, visit the Enterprise Plan page.
The date and time when the session will expire. The default is 90 days from the time of the request. The minimum value is 10 minutes from the time of the request. The maximum value is 1 year from the time of the request. Example: 2024-07-21 or 2024-07-21T13:58:46
The message to display to the user when the session expires. The default message is “This session has expired.” When setting this message, you may want to provide basic instructions for the user to contact you to request a new form.
The formData object can include settable properties from the specified formType. The data set will be carried over to the form object, but may be edited by the user completing the form. Refer to the form object guides for settable properties.