Documentation › Use Plumsail Forms as REST API

Use Plumsail Forms as REST API

Plumsail Forms provides a REST API that allows you to manage forms, submissions, and other resources programmatically.

Swagger API Reference

You can find the Swagger API reference for Plumsail Forms at:

Authentication

The Plumsail Forms API uses OAuth 2.0 authentication. This method allows your application to access the API on behalf of users securely.

OAuth 2.0 Configuration:

Authorization URL: https://auth.plumsail.com/connect/authorize
Token URL: https://auth.plumsail.com/connect/token
Client ID and Secret: Submit a request to our support team and provide a description of your integration: support@plumsail.com

Use API from your programming language

Our API is REST-based. Thus, you can use any programming language that can execute web requests. For example, you would use C#, PowerShell, node.js, Python, PHP.

There are a lot of ready to use helper REST API clients for those languages. Here are just a few of them:

Common API operations

Get all public forms

Below is an example of a curl request to retrieve all your public forms:

curl --location --request GET 'https://forms.plumsail.com/api/v2/designer/forms' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

The response will return an array of your public forms with their configurations and metadata.

Response codes:

  • 200 OK - Returns an array of public forms

  • 401 Unauthorized - Authorization information is missing or invalid

Download an attachment

To download an attachment by its URL:

curl --location --request GET 'https://forms.plumsail.com/api/attachments?fileUrl={fileUrl}'

Parameters:

  • fileUrl - The URL of the attachment file (query parameter)

Response codes:

  • 200 OK - The contents of the attachment

  • 400 Bad Request - Invalid request

Delete an attachment

To delete an attachment by its URL:

curl --location --request DELETE 'https://forms.plumsail.com/api/attachments?fileUrl={fileUrl}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Parameters:

  • fileUrl - The URL of the attachment file (body parameter, as a JSON string)

Response codes:

  • 204 No Content - Attachment successfully deleted

  • 401 Unauthorized - Authorization information is missing or invalid

Get form schema

To retrieve the schema of a specific form:

curl --location --request GET 'https://forms.plumsail.com/api/flow/schema/form?formId={formId}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Parameters:

  • formId - The unique identifier (UUID) of your form (query parameter)

The response will return the form schema. The schema is returned as an object containing form field definitions and structure.

Response codes:

  • 200 OK - Returns form schema

  • 401 Unauthorized - Authorization information is missing or invalid

Delete a form submission

You can delete a specific form submission using the API:

curl --location --request DELETE 'https://forms.plumsail.com/api/forms/{formId}/submissions/{submissionId}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Parameters:

  • formId - The unique identifier (UUID) of the form (path parameter)

  • submissionId - The ID of the submission you want to delete (path parameter)

Response codes:

  • 204 No Content - Submission successfully deleted

  • 401 Unauthorized - Authorization information is missing or invalid

  • 404 Not Found - Form was not found

Working with submission triggers

The Plumsail Forms API supports webhook-style subscription to form submission events. This allows you to receive real-time notifications when forms are submitted.

Subscribe to form submissions

To subscribe to form submission events:

curl --location --request POST 'https://forms.plumsail.com/api/submissions' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data-raw '{
    "formId": "{formId}",
    "callbackUrl": "https://your-domain.com/webhook-endpoint"
  }'

Parameters (in request body):

  • formId - The UUID of the form you want to monitor (required)

  • callbackUrl - Your endpoint URL that will receive submission notifications (required, minimum length: 1)

When a form is submitted, your endpoint will receive a POST request with the submission data.

Response codes:

  • 201 Created - Subscription has been created

  • 400 Bad Request - Invalid subscription configuration

  • 401 Unauthorized - Authorization information is missing or invalid

Unsubscribe from form submissions

To remove a subscription:

curl --location --request DELETE 'https://forms.plumsail.com/api/submissions/{subscriberId}'

Parameters:

  • subscriberId - The unique identifier (UUID) of the subscription you want to remove (path parameter)

Response codes:

  • 200 OK - Subscription successfully removed

Best practices

  1. Store credentials securely - Never expose your client_id, client_secret, or access tokens in client-side code or public repositories

  2. Use environment variables - Store OAuth credentials and access tokens in environment variables for better security

  3. Handle errors gracefully - Implement proper error handling for all API calls, especially 401 Unauthorized responses

  4. Use webhooks for real-time data - Subscribe to submission events using the SubmissionTrigger endpoint for real-time notifications

  5. Cache form schemas - Form schemas rarely change (unless you update the form), so you can cache them to reduce unnecessary API calls

  6. Use HTTPS only - All API requests must use HTTPS

Example: Complete workflow

Here’s a complete example workflow showing how to use the API:

Step 1: Get your forms

curl --location --request GET 'https://forms.plumsail.com/api/v2/designer/forms' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Step 2: Get schema for a specific form

curl --location --request GET 'https://forms.plumsail.com/api/flow/schema/form?formId={formId}' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Step 3: Subscribe to form submissions

curl --location --request POST 'https://forms.plumsail.com/api/submissions' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data-raw '{
    "formId": "{formId}",
    "callbackUrl": "https://your-domain.com/webhook"
  }'

Step 4: Receive submissions at your webhook

Your webhook endpoint will receive POST requests when the form is submitted.

Step 5: Delete old submissions

curl --location --request DELETE 'https://forms.plumsail.com/api/forms/{formId}/submissions/{submissionId}' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Step 6: Download or delete attachments

Download an attachment:

curl --location --request GET 'https://forms.plumsail.com/api/attachments?fileUrl={fileUrl}'

Delete an attachment:

curl --location --request DELETE 'https://forms.plumsail.com/api/attachments?fileUrl={fileUrl}' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'