Introduction

The Partner Subaccount REST API allows Parent Organization Administrators to provision (create) new Subaccounts and configure them with products, components, and extras. Read on to learn how to integrate with our API.

The process of provisioning Subaccounts consists of three steps, as shown in the diagram below.

Subaccount provisioning process

The following sections explain in detail how Subaccount provisioning works.

1. Requesting the List of Products Available for Provisioning

Executing this step is optional if you are already familiar with the product catalog available to your Parent Organization. However, you can use the information provided to validate your subsequent requests.

Request

HTTP Method: GET

URL:https://admin.formstack.com/api/v1/organizations/{organizationId}/subaccounts/products

📖 API Reference

Sample response

The example below, provided for documentation purposes, shows a limited subset of available products.

HTTP Status: 200 OK

{
   "products": {
       "plans": [
           {
                "handle": "p:formstack-2024-docs",
                "name": "Formstack Documents"
           },
           {
               "handle": "p:forms-starter",
               "name": "Forms Starter"
           }
       ],
       "extras": [
           {
                "handle": "c:platform-plan-extra-full-access-user",
                "name": "Builder User"
           },
           {
               "handle": "c:platform-plan-forms-extra-1k-submissions",
               "name": "Forms: Pack of 1000 submissions"
           }
       ],
       "addons": [
           {
                "handle": "c:platform-plan-api",
                "name": "Formstack API"
           },
           {
               "handle": "c:forms-portals",
               "name": "Forms: Portals Addon"
           }
       ]
   }
}

Products in the plans section are recurring plans that the new Subaccount can subscribe to.

Products in the extras section provide additional usage for plans and can be purchased in volume.

Finally, addons enable additional features on the Subaccount. Only one add-on can be ordered per Subaccount.

2. Validate and Preview a New Subaccount Billing

This endpoint allows you to validate the billing request and preview the Subaccount billing.

Request

HTTP Method: POST

URL: https://admin.formstack.com/api/v1/organizations/{organizationId}/subaccounts/preview

body:

{
   "periodicity": null,
   "productHandles": [
       "p:formstack-2024-docs",
       "c:platform-plan-extra-full-access-user:3",
       "c:platform-plan-api"
   ]
}

In the example above, we're creating a Subaccount with a Formstack Documents plan, requesting 3 Builder users, and enabling the API extension.

📖 API Reference

Sample response

HTTP Status: 200 OK

{
   "immediateCharge": {
       "amount": "5000",
       "currency": "USD",
       "formatted": "$50"
   },
   "regularCharge": {
       "amount": "7000",
       "currency": "USD",
       "formatted": "$70"
   },
   "discount": {
       "name": "Strategic reseller discount",
       "handle": "d:reseller-discount-gold",
       "percentage": 30,
       "saving": {
           "amount": "3000",
           "currency": "USD",
           "formatted": "$30"
       }
   }
}

3. Create a New Subaccount

In this step, the client must send the same billing details validated in the previous step, along with the new Organization details.

Request

HTTP Method: POST

URL: https://admin.formstack.com/api/v1/organizations/{organizationId}/subaccounts

body:

{
   "orgName": "BioSpark",
   "firstName": "Rafal",
   "lastName": "Trzaskowski",
   "email": "[email protected]",
   "hipaa": false,
   "logoBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
   "periodicity": null,
   "productHandles": [
       "p:formstack-2024-docs",
       "c:platform-plan-extra-full-access-user:3",
       "c:platform-plan-api"
   ]
}

📖 API Reference

Sample response

HTTP Status: 200 OK

{
    "id": "d5cae646-24df-11f0-8f44-0242ac000006",
    "name": "BioSpark",
    "appIds": {
        "docs": null
    },
    "appUsage": {
        "docs": [
            {
                "label": "Users",
                "current": 0,
                "currentFormatted": null,
                "limit": 4,
                "limitFormatted": null,
                "warningMessage": null,
                "validUntil": null
            },
            {
                "label": "Live Merges",
                "current": 0,
                "currentFormatted": null,
                "limit": 50,
                "limitFormatted": null,
                "warningMessage": null,
                "validUntil": null
            },
            {
                "label": "Test Merges",
                "current": 0,
                "currentFormatted": null,
                "limit": 50,
                "limitFormatted": null,
                "warningMessage": null,
                "validUntil": null
            }
        ]
    },
    "appAdmins": {
        "docs": null
    }
}

Once the request is processed, the new Subaccount is created and billing is initiated accordingly.

Sample error response

HTTP Status: 422 Unprocessable entity

{
    "message": "The email has already been taken.",
    "errors": {
        "email": [
            "The email has already been taken."
        ]
    }
}