API Quickstart

Nextform helps you collect, generate, and keep track of commonly requested forms like W-9s with an API that is easy to implement and white label forms that show your organization's name and brand.

Step 1: Create an Account

Sign up for a free account. No credit card is required, and you'll get 20 free forms to test your implementation. If you need more forms for testing, just contact us!

Once you've created an account, navigate to the developer settings and generate an API key. API keys are randomly generated, and you may generate up to three. This makes it easy to rotate API keys if needed. Treat your API key like a password and keep it secure.

Step 2: Create a Session

Using the tool of your choice (you may be interested in using Postman or VS Code REST Client for experimentation) set up your first POST request. We are going to create a session to collect a W-9. The only required property is formType, but we are also going to set a reference string here, which will help us find the form later. You may want to use an internal user ID as your reference string, or anything that will help you to associate the session with one of your users.

Note that we are authenticating this request by including the API key in the Authorization header. There are a variety of ways to authenticate your request, but this is the recommended approach.

POST https://api.nextform.app/sessions HTTP/1.1
Content-Type: application/json
Authorization: PUT_YOUR_API_KEY_HERE

{
  "formType": "w9Oct2018",
  "reference": "123"
}

When your session is successfully created, the response includes a session object with a url that you can pass to your user. The url is a link to a hosted white label form that can display your organization's name and logo.

{
  "id": "v6v93Z6WfYMo6AbfG1o1y7",
  "reference": "123",
  "status": "open",
  "url": "https://nextform.app/form/w9Oct2018/v6v93Z6WfYMo6AbfG1o1y7",
  "successUrl": null,
  "signerEmail": null,
  "formType": "w9Oct2018",
  "formData": null
}

Step 3: Complete the Form

In your actual implementation, this is the point where you would provide your user with a link, or redirect them to the url in the session object. For now, you can just copy and paste the url value into a browser window. It will take you to a user-friendly W-9 form that works on desktop or mobile. (If you skipped ahead to this step and you just want to see the form in action, you can check out the demo form.)

The form includes built-in validation and guidance to help your user complete the form correctly and accurately. Tooltips address common questions and can eliminate support requests.

Once the form is completed, click the "Send Form" button. This kicks off a few processes. The form is validated again on the server, and a PDF of the official form is generated. If you have set up a webhook endpoint, a webhook is delivered to your server with all of the form data.

Step 4: Retrieve the Form

Once a form has been submitted, Nextform permanently stores the form data and the PDF, and it can be retrieved at any time. The simplest method is to list the latest forms:

GET https://api.nextform.app/forms HTTP/1.1

By default this will return an array of the 10 latest forms. However, you may want to filter this down to a particular user. If you set the reference string earlier, you may add a query parameter to filter on your reference string:

GET https://api.nextform.app/forms?reference=123 HTTP/1.1

This will return an array of forms with a reference string that matches your query. There are a variety of ways to list and filter forms. Learn more about the different available query parameters on the list forms document.

If you would like a PDF of the form, you can easily request an url to download the PDF with a GET request that includes the form ID:

GET https://api.nextform.app/forms/v6v93Z6WfYMo6AbfG1o1y7/pdf HTTP/1.1

If you want to receive a webhook as soon as a new form is submitted, it is easy to set up a webhook endpoint in your developer settings. This will save you from constantly polling Nextform for new forms. If a webhook is not successfully delivered, it will be retried for up to 24 hours with an exponential back off.

Next Steps

As you can see, it is easy to fit Nextform into your user onboarding process. You may rely on Nextform to securely store and manage your forms, or copy data as needed to your own services for internal handling.

If Nextform is a good fit for your organization, we offer affordable monthly or yearly pricing which gives you unlimited access to the API. We understand that we are handling your most sensitive data, which is why we continually test all of our API endpoints using the 2021 OWASP Top Ten principles. All Nextform data is encrypted in transit and at rest and we do not share data with any other entity.