Create Form

Create Form

curl --request POST \
  --url https://connect.penbox.io/v1/forms \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "flow": {
    "slug": "client-onboarding"
  },
  "user": {
    "email": "client@example.com",
    "given_name": "John",
    "family_name": "Doe"
  },
  "data": {
    "company_name": "Acme Corporation",
    "company_vat": "BE0123456789",
    "address_street": "123 Main Street",
    "address_city": "New York",
    "address_zip": "10001",
    "address_country": "US",
    "annual_revenue": "1500000",
    "number_employees": "25"
  },
  "external_args": {
    "crm_id": "12345"
  },
  "branding": {
    "slug": "partner-brand"
  }
}
'

import requests

url = "https://connect.penbox.io/v1/forms"

payload = {
    "flow": { "slug": "client-onboarding" },
    "user": {
        "email": "client@example.com",
        "given_name": "John",
        "family_name": "Doe"
    },
    "data": {
        "company_name": "Acme Corporation",
        "company_vat": "BE0123456789",
        "address_street": "123 Main Street",
        "address_city": "New York",
        "address_zip": "10001",
        "address_country": "US",
        "annual_revenue": "1500000",
        "number_employees": "25"
    },
    "external_args": { "crm_id": "12345" },
    "branding": { "slug": "partner-brand" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    flow: {slug: 'client-onboarding'},
    user: {email: 'client@example.com', given_name: 'John', family_name: 'Doe'},
    data: {
      company_name: 'Acme Corporation',
      company_vat: 'BE0123456789',
      address_street: '123 Main Street',
      address_city: 'New York',
      address_zip: '10001',
      address_country: 'US',
      annual_revenue: '1500000',
      number_employees: '25'
    },
    external_args: {crm_id: '12345'},
    branding: {slug: 'partner-brand'}
  })
};

fetch('https://connect.penbox.io/v1/forms', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://connect.penbox.io/v1/forms",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'flow' => [
        'slug' => 'client-onboarding'
    ],
    'user' => [
        'email' => 'client@example.com',
        'given_name' => 'John',
        'family_name' => 'Doe'
    ],
    'data' => [
        'company_name' => 'Acme Corporation',
        'company_vat' => 'BE0123456789',
        'address_street' => '123 Main Street',
        'address_city' => 'New York',
        'address_zip' => '10001',
        'address_country' => 'US',
        'annual_revenue' => '1500000',
        'number_employees' => '25'
    ],
    'external_args' => [
        'crm_id' => '12345'
    ],
    'branding' => [
        'slug' => 'partner-brand'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://connect.penbox.io/v1/forms"

	payload := strings.NewReader("{\n  \"flow\": {\n    \"slug\": \"client-onboarding\"\n  },\n  \"user\": {\n    \"email\": \"client@example.com\",\n    \"given_name\": \"John\",\n    \"family_name\": \"Doe\"\n  },\n  \"data\": {\n    \"company_name\": \"Acme Corporation\",\n    \"company_vat\": \"BE0123456789\",\n    \"address_street\": \"123 Main Street\",\n    \"address_city\": \"New York\",\n    \"address_zip\": \"10001\",\n    \"address_country\": \"US\",\n    \"annual_revenue\": \"1500000\",\n    \"number_employees\": \"25\"\n  },\n  \"external_args\": {\n    \"crm_id\": \"12345\"\n  },\n  \"branding\": {\n    \"slug\": \"partner-brand\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://connect.penbox.io/v1/forms")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"flow\": {\n    \"slug\": \"client-onboarding\"\n  },\n  \"user\": {\n    \"email\": \"client@example.com\",\n    \"given_name\": \"John\",\n    \"family_name\": \"Doe\"\n  },\n  \"data\": {\n    \"company_name\": \"Acme Corporation\",\n    \"company_vat\": \"BE0123456789\",\n    \"address_street\": \"123 Main Street\",\n    \"address_city\": \"New York\",\n    \"address_zip\": \"10001\",\n    \"address_country\": \"US\",\n    \"annual_revenue\": \"1500000\",\n    \"number_employees\": \"25\"\n  },\n  \"external_args\": {\n    \"crm_id\": \"12345\"\n  },\n  \"branding\": {\n    \"slug\": \"partner-brand\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://connect.penbox.io/v1/forms")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"flow\": {\n    \"slug\": \"client-onboarding\"\n  },\n  \"user\": {\n    \"email\": \"client@example.com\",\n    \"given_name\": \"John\",\n    \"family_name\": \"Doe\"\n  },\n  \"data\": {\n    \"company_name\": \"Acme Corporation\",\n    \"company_vat\": \"BE0123456789\",\n    \"address_street\": \"123 Main Street\",\n    \"address_city\": \"New York\",\n    \"address_zip\": \"10001\",\n    \"address_country\": \"US\",\n    \"annual_revenue\": \"1500000\",\n    \"number_employees\": \"25\"\n  },\n  \"external_args\": {\n    \"crm_id\": \"12345\"\n  },\n  \"branding\": {\n    \"slug\": \"partner-brand\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "archived": true,
  "archived_at": "2023-11-07T05:31:56Z",
  "processed_at": "2023-11-07T05:31:56Z",
  "active_from": "2023-11-07T05:31:56Z",
  "active_until": "2023-11-07T05:31:56Z",
  "links": {
    "fill": "<string>",
    "app": "<string>"
  },
  "user": {
    "anonymous": true,
    "email": "<string>",
    "phone": "<string>",
    "given_name": "<string>",
    "family_name": "<string>",
    "company_name": "<string>",
    "internal_ref": "<string>"
  },
  "owner": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "email": "<string>"
  },
  "flow": {
    "slug": "<string>"
  },
  "data": {},
  "external_args": {},
  "options": {},
  "responses": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "completed_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "data": {},
      "user": {
        "anonymous": true,
        "ip": "<string>",
        "email": "<string>",
        "phone": "<string>",
        "locale": "<string>",
        "given_name": "<string>",
        "family_name": "<string>",
        "user-agent": "<string>",
        "accept-language": "<string>"
      },
      "attachments": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>",
          "type": "<string>",
          "scope": "<string>",
          "data": "<string>",
          "metadata": {
            "size": 123,
            "width": 123,
            "height": 123
          },
          "uri": "<string>"
        }
      ],
      "signatures": {},
      "files": {}
    }
  ],
  "notifications": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "at": "2023-11-07T05:31:56Z",
      "to": "<string>",
      "from": "<string>",
      "cc": "<string>",
      "bcc": "<string>",
      "system": true,
      "locale": "<string>",
      "template": "<string>",
      "variables": {},
      "active": true,
      "error": "<string>",
      "message_id": "<string>",
      "attachments": {},
      "deleted_at": "2023-11-07T05:31:56Z"
    }
  ],
  "webhooks": {}
}

POST

forms

Create Form

curl --request POST \
  --url https://connect.penbox.io/v1/forms \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "flow": {
    "slug": "client-onboarding"
  },
  "user": {
    "email": "client@example.com",
    "given_name": "John",
    "family_name": "Doe"
  },
  "data": {
    "company_name": "Acme Corporation",
    "company_vat": "BE0123456789",
    "address_street": "123 Main Street",
    "address_city": "New York",
    "address_zip": "10001",
    "address_country": "US",
    "annual_revenue": "1500000",
    "number_employees": "25"
  },
  "external_args": {
    "crm_id": "12345"
  },
  "branding": {
    "slug": "partner-brand"
  }
}
'

import requests

url = "https://connect.penbox.io/v1/forms"

payload = {
    "flow": { "slug": "client-onboarding" },
    "user": {
        "email": "client@example.com",
        "given_name": "John",
        "family_name": "Doe"
    },
    "data": {
        "company_name": "Acme Corporation",
        "company_vat": "BE0123456789",
        "address_street": "123 Main Street",
        "address_city": "New York",
        "address_zip": "10001",
        "address_country": "US",
        "annual_revenue": "1500000",
        "number_employees": "25"
    },
    "external_args": { "crm_id": "12345" },
    "branding": { "slug": "partner-brand" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    flow: {slug: 'client-onboarding'},
    user: {email: 'client@example.com', given_name: 'John', family_name: 'Doe'},
    data: {
      company_name: 'Acme Corporation',
      company_vat: 'BE0123456789',
      address_street: '123 Main Street',
      address_city: 'New York',
      address_zip: '10001',
      address_country: 'US',
      annual_revenue: '1500000',
      number_employees: '25'
    },
    external_args: {crm_id: '12345'},
    branding: {slug: 'partner-brand'}
  })
};

fetch('https://connect.penbox.io/v1/forms', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://connect.penbox.io/v1/forms",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'flow' => [
        'slug' => 'client-onboarding'
    ],
    'user' => [
        'email' => 'client@example.com',
        'given_name' => 'John',
        'family_name' => 'Doe'
    ],
    'data' => [
        'company_name' => 'Acme Corporation',
        'company_vat' => 'BE0123456789',
        'address_street' => '123 Main Street',
        'address_city' => 'New York',
        'address_zip' => '10001',
        'address_country' => 'US',
        'annual_revenue' => '1500000',
        'number_employees' => '25'
    ],
    'external_args' => [
        'crm_id' => '12345'
    ],
    'branding' => [
        'slug' => 'partner-brand'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://connect.penbox.io/v1/forms"

	payload := strings.NewReader("{\n  \"flow\": {\n    \"slug\": \"client-onboarding\"\n  },\n  \"user\": {\n    \"email\": \"client@example.com\",\n    \"given_name\": \"John\",\n    \"family_name\": \"Doe\"\n  },\n  \"data\": {\n    \"company_name\": \"Acme Corporation\",\n    \"company_vat\": \"BE0123456789\",\n    \"address_street\": \"123 Main Street\",\n    \"address_city\": \"New York\",\n    \"address_zip\": \"10001\",\n    \"address_country\": \"US\",\n    \"annual_revenue\": \"1500000\",\n    \"number_employees\": \"25\"\n  },\n  \"external_args\": {\n    \"crm_id\": \"12345\"\n  },\n  \"branding\": {\n    \"slug\": \"partner-brand\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://connect.penbox.io/v1/forms")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"flow\": {\n    \"slug\": \"client-onboarding\"\n  },\n  \"user\": {\n    \"email\": \"client@example.com\",\n    \"given_name\": \"John\",\n    \"family_name\": \"Doe\"\n  },\n  \"data\": {\n    \"company_name\": \"Acme Corporation\",\n    \"company_vat\": \"BE0123456789\",\n    \"address_street\": \"123 Main Street\",\n    \"address_city\": \"New York\",\n    \"address_zip\": \"10001\",\n    \"address_country\": \"US\",\n    \"annual_revenue\": \"1500000\",\n    \"number_employees\": \"25\"\n  },\n  \"external_args\": {\n    \"crm_id\": \"12345\"\n  },\n  \"branding\": {\n    \"slug\": \"partner-brand\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://connect.penbox.io/v1/forms")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"flow\": {\n    \"slug\": \"client-onboarding\"\n  },\n  \"user\": {\n    \"email\": \"client@example.com\",\n    \"given_name\": \"John\",\n    \"family_name\": \"Doe\"\n  },\n  \"data\": {\n    \"company_name\": \"Acme Corporation\",\n    \"company_vat\": \"BE0123456789\",\n    \"address_street\": \"123 Main Street\",\n    \"address_city\": \"New York\",\n    \"address_zip\": \"10001\",\n    \"address_country\": \"US\",\n    \"annual_revenue\": \"1500000\",\n    \"number_employees\": \"25\"\n  },\n  \"external_args\": {\n    \"crm_id\": \"12345\"\n  },\n  \"branding\": {\n    \"slug\": \"partner-brand\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "archived": true,
  "archived_at": "2023-11-07T05:31:56Z",
  "processed_at": "2023-11-07T05:31:56Z",
  "active_from": "2023-11-07T05:31:56Z",
  "active_until": "2023-11-07T05:31:56Z",
  "links": {
    "fill": "<string>",
    "app": "<string>"
  },
  "user": {
    "anonymous": true,
    "email": "<string>",
    "phone": "<string>",
    "given_name": "<string>",
    "family_name": "<string>",
    "company_name": "<string>",
    "internal_ref": "<string>"
  },
  "owner": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "email": "<string>"
  },
  "flow": {
    "slug": "<string>"
  },
  "data": {},
  "external_args": {},
  "options": {},
  "responses": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "completed_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "data": {},
      "user": {
        "anonymous": true,
        "ip": "<string>",
        "email": "<string>",
        "phone": "<string>",
        "locale": "<string>",
        "given_name": "<string>",
        "family_name": "<string>",
        "user-agent": "<string>",
        "accept-language": "<string>"
      },
      "attachments": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>",
          "type": "<string>",
          "scope": "<string>",
          "data": "<string>",
          "metadata": {
            "size": 123,
            "width": 123,
            "height": 123
          },
          "uri": "<string>"
        }
      ],
      "signatures": {},
      "files": {}
    }
  ],
  "notifications": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "at": "2023-11-07T05:31:56Z",
      "to": "<string>",
      "from": "<string>",
      "cc": "<string>",
      "bcc": "<string>",
      "system": true,
      "locale": "<string>",
      "template": "<string>",
      "variables": {},
      "active": true,
      "error": "<string>",
      "message_id": "<string>",
      "attachments": {},
      "deleted_at": "2023-11-07T05:31:56Z"
    }
  ],
  "webhooks": {}
}

Request Parameters

Required Fields

Field	Type	Description
`flow.slug`	string	Form template identifier

Optional Fields

Field	Type	Description
`company.slug`	string	Workspace identifier (if multiple authorized)
`user.email`	string	Contact email address
`user.phone`	string	Contact phone number
`user.given_name`	string	Contact first name
`user.family_name`	string	Contact last name
`user.locale`	string	Contact language (e.g., `en`, `fr`)
`data`	object	Pre-filled form data (keys must match form field keys)
`external_args`	object	Your custom metadata
`redirect_url`	string	HTTPS URL to redirect after completion
`draft`	boolean	Create as draft (default: `false`)
`active_from`	string	ISO 8601 date when form becomes active
`active_until`	string	ISO 8601 date when form expires
`owner.email`	string	Form owner email address
`branding.slug`	string	Branding profile slug (see Branding below)

Form Statuses

Status	Description
`draft`	Form created but not yet sent
`pending`	Form sent, waiting for completion
`completed`	Contact submitted the form
`declined`	Contact declined to fill the form
`processed`	Response has been reviewed/processed

Pre-filling Form Data

The data parameter allows you to pre-fill form fields with values. This is useful for importing data from your system or providing a better user experience by reducing the amount of information the contact needs to enter.

How It Works

The keys in the data object must exactly match the field keys defined in your form template. When a contact opens the form, these fields will already contain the provided values. Example: If your form template has fields with keys:

company_name
address_zip
annual_revenue

You can pre-fill them like this:

{
  "data": {
    "company_name": "Acme Corp",
    "address_zip": "10001",
    "annual_revenue": "500000"
  }
}

Finding Field Keys

Field keys are defined in your form template configuration in Penbox. Common examples:

Field Type	Example Keys
Company Info	`company_name`, `company_vat`, `company_registration`
Address	`address_street`, `address_city`, `address_zip`, `address_country`
Contact	`contact_name`, `contact_email`, `contact_phone`
Financial	`annual_revenue`, `number_employees`, `bank_account`
Custom	Any custom field keys you’ve defined in your template

Field keys are case-sensitive and must match exactly. Use the Penbox app or contact your administrator to find the correct field keys for your form template.

Complete Example

const response = await fetch('https://connect.penbox.io/v1/forms', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    flow: { slug: 'client-onboarding' },
    user: {
      email: 'client@example.com',
      given_name: 'John',
      family_name: 'Doe'
    },
    // Pre-fill form fields
    data: {
      company_name: 'Acme Corporation',
      company_vat: 'BE0123456789',
      address_street: '123 Main Street',
      address_city: 'New York',
      address_zip: '10001',
      address_country: 'US',
      annual_revenue: '1500000',
      number_employees: '25'
    },
    external_args: {
      crm_id: '12345'
    },
    branding: {
      slug: 'partner-brand'
    }
  })
});

cURL

curl -X POST 'https://connect.penbox.io/v1/forms' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": { "slug": "client-onboarding" },
    "user": {
      "email": "client@example.com",
      "given_name": "John",
      "family_name": "Doe"
    },
    "data": {
      "company_name": "Acme Corporation",
      "company_vat": "BE0123456789",
      "address_street": "123 Main Street",
      "address_city": "New York",
      "address_zip": "10001",
      "address_country": "US",
      "annual_revenue": "1500000",
      "number_employees": "25"
    },
    "external_args": {
      "crm_id": "12345"
    },
    "branding": {
      "slug": "partner-brand"
    }
  }'

Use Cases

Import from CRM:

// Pull data from your CRM and pre-fill the form
const crmContact = await getCRMContact(contactId);

const formData = {
  company_name: crmContact.companyName,
  address_zip: crmContact.zipCode,
  annual_revenue: crmContact.revenue,
  contact_phone: crmContact.phone
};

await createForm({ 
  flow: { slug: 'onboarding' },
  user: { email: crmContact.email },
  data: formData 
});

Progressive Forms:

// Pre-fill with data collected in previous steps
const formData = {
  company_name: step1Data.company,
  address_zip: step2Data.zip,
  business_type: step3Data.type
};

Reduce Friction:

// Pre-fill known information to make the form faster
const formData = {
  company_name: user.organization,
  contact_email: user.email,
  contact_phone: user.phone
};

Pre-filling data improves form completion rates and reduces errors. Always pre-fill what you know while allowing contacts to modify values if needed.

If you provide a field key that doesn’t exist in the form template, it will be silently ignored. Make sure your field keys match your template configuration.

Branding

Use the branding parameter to apply a specific visual identity to a form — logo, colors, favicon, and related styling in the form experience and email notifications.

Default behavior

When branding is omitted, the form uses your workspace’s default branding — the profile configured under Settings → Branding in Penbox.

How it works

Pass the slug of an existing branding profile in your workspace:

{
  "flow": { "slug": "client-onboarding" },
  "user": { "email": "client@example.com" },
  "branding": {
    "slug": "partner-brand"
  }
}

The slug must match a branding profile that already exists in the workspace. If the slug is invalid or not found, the API returns 404.

To use the workspace default branding, omit the branding field entirely. The slug default is only a UI label for the primary workspace profile — it is not a valid API value.

Finding the branding slug

Open Settings → Branding in Penbox.
If your workspace has multiple branding profiles, select the profile you want and note its slug — it is displayed next to the profile selector (for example, slug: partner-brand).

See Branding for how to create and manage branding profiles.

Use cases

White-label partner forms:

await createForm({
  flow: { slug: 'onboarding' },
  user: { email: partner.contactEmail },
  branding: { slug: 'partner-acme' }
});

Different brands per client segment:

const brandingSlug = client.segment === 'enterprise'
  ? 'enterprise-brand'
  : 'self-serve-brand';

await createForm({
  flow: { slug: 'signup' },
  user: { email: client.email },
  branding: { slug: brandingSlug }
});

Branding is set at form creation and applies to the form link and related emails for that form. Create separate branding profiles in Penbox when you need distinct visual identities for different clients or product lines.

External Args

Use external_args to store your own metadata with forms for easy tracking:

{
  "external_args": {
    "crm_id": "12345",
    "order_id": "ORD-789",
    "source": "website",
    "campaign": "summer-2024"
  }
}

You can filter by external_args when listing forms:

{
  "filter": {
    "external_args": {
      "order_id": "ORD-789"
    }
  }
}

Response Codes

Code	Description
`201`	Created - New form created successfully
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid access token
`403`	Forbidden - No access to this resource
`409`	Conflict - Multiple form templates match criteria
`422`	Unprocessable - Validation failed
`429`	Too Many Requests - Rate limit exceeded
`500`	Server Error - Internal error

Created forms are immediately active unless draft: true is specified. Draft forms must be activated by setting draft: false via PATCH.

Use external_args to link Penbox forms back to your system’s entities (orders, customers, tickets, etc.). This makes it easy to track and manage forms in your system.

The active_from and active_until dates control when the form link is accessible. Set active_until to create expiring forms.

Authorizations

Authorization

string

header

required

API token (starts with pnbx_). Create at https://app.penbox.io/workspace/settings/api. Include as: Authorization: Bearer {token}

Body

application/json

flow

object

required

Show child attributes

workspace

object

Show child attributes

user

object

Show child attributes

data

object

Pre-filled form data

external_args

object

Your custom metadata

redirect_url

string<uri>

HTTPS URL to redirect after completion

draft

boolean

default:false

Create as draft (not active)

options

object

Form-specific options

active_from

string<date-time>

ISO 8601 date when form becomes active

active_until

string<date-time>

ISO 8601 date when form expires

owner

object

Show child attributes

branding

object

Branding profile to apply to the form. Omit to use the workspace default.

Show child attributes

Response

201 - application/json

Form created successfully

string<uuid>

Form UUID

created_at

string<date-time>

Creation timestamp

status

enum<string>

Current form status

Available options:

draft,

pending,

completed,

declined,

processed

archived

boolean

Whether the form is archived

archived_at

string<date-time> | null

Timestamp when archived

processed_at

string<date-time> | null

Timestamp when marked as processed

active_from

string<date-time> | null

When the form becomes active

active_until

string<date-time> | null

When the form expires

links

object

URLs for accessing the form

Show child attributes

user

object

Contact information

Show child attributes

owner

object | null

Form owner information

Show child attributes

flow

object

Form template information

Show child attributes

data

object

Pre-filled form data

external_args

object | null

Custom metadata

options

object | null

Form-specific options

responses

object[]

Array of form responses

Show child attributes

notifications

object[]

Array of notifications sent for this form

Show child attributes

webhooks

object | null

Webhook URLs with event subscriptions

Show child attributes

API Reference

Workspaces

Cases

Case Templates

Forms

Form Templates

Attachments

Document Intelligence

Signatures

Previous API version

Request Parameters

Required Fields

Optional Fields

Form Statuses

Pre-filling Form Data

How It Works

Finding Field Keys

Complete Example

Use Cases

Branding

Default behavior

How it works

Finding the branding slug

Use cases

External Args

Response Codes

Authorizations

Body

Response

​Request Parameters

​Required Fields

​Optional Fields

​Form Statuses

​Pre-filling Form Data

​How It Works

​Finding Field Keys

​Complete Example

​Use Cases

​Branding

​Default behavior

​How it works

​Finding the branding slug

​Use cases

​External Args

​Response Codes

Authorizations

Body

Response

Request Parameters

Required Fields

Optional Fields

Form Statuses

Pre-filling Form Data

How It Works

Finding Field Keys

Complete Example

Use Cases

Branding

Default behavior

How it works

Finding the branding slug

Use cases

External Args

Response Codes