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. At a minimum, the form session should specify the formType. 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": 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",
"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 form type as an enum string. You may have noticed in the example above that the type property is a combination of the form name and the form revision. This is because official bodies revise their forms from time to time and our service is designed to precisely target a specific version of a form. When standard forms are revised, Nextform develops a new form type that you may begin requesting when you and your systems are ready.
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.