Skip to main content
GET
/
flows
curl -X GET 'https://connect.penbox.io/v1/flows' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "flow_customizations",
      "attributes": {
        "name": "<string>",
        "enabled": true,
        "options": {}
      },
      "relationships": {
        "flow": {
          "data": {
            "id": "<string>",
            "type": "flows"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "flows",
      "attributes": {
        "slug": "<string>",
        "name": "<string>",
        "version": 123,
        "locale": "<string>"
      }
    }
  ]
}
Retrieve all active form templates (API: flows) available in the authorized workspaces.
In the API, form templates are referred to as flows. This is the technical term used in all endpoints and parameters.
curl -X GET 'https://connect.penbox.io/v1/flows' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

​
Query Parameters

ParameterTypeDefaultDescription
archivedbooleanfalseInclude archived templates when true

​
Response Structure

The response returns an array of form template objects directly:
FieldTypeDescription
idstringTemplate configuration UUID
created_atstringISO 8601 creation timestamp
slugstringUnique identifier used in API calls
namestringTemplate display name
archived_atstringISO 8601 timestamp if archived, otherwise null
enabledbooleanWhether the template is active

​
Template Slug

Use the template slug (API: flow.slug) to create forms: 
{
  "flow": { "slug": "client-onboarding" }
}
Slug format:
  • Lowercase letters, numbers, and hyphens
  • No spaces or special characters
  • Unique within a workspace

​
Use Cases

​
Discover Available Templates

List all form templates a user can send from your application: 
async function getAvailableTemplates(accessToken) {
  const response = await fetch('https://connect.penbox.io/v1/flows', {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  });

  const flows = await response.json(); // Returns array directly

  // Filter to enabled and active templates only
  return flows
    .filter(flow => flow.enabled && !flow.archived_at)
    .map(flow => ({
      id: flow.id,
      slug: flow.slug,
      name: flow.name
    }));
}

​
Check Template Configuration

Before creating a form, check the template’s configuration: 
async function checkTemplateConfig(accessToken, templateSlug) {
  const response = await fetch('https://connect.penbox.io/v1/flows', {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  });

  const flows = await response.json(); // Returns array directly

  // Find template by slug
  const flow = flows.find(f => f.slug === templateSlug);

  if (!flow) {
    throw new Error(`Template ${templateSlug} not found`);
  }

  return {
    id: flow.id,
    slug: flow.slug,
    name: flow.name,
    enabled: flow.enabled,
    archived: flow.archived_at !== null
  };
}

​
Response Codes

CodeDescription
200Success - Returns template data
401Unauthorized - Invalid or expired access token
403Forbidden - No access to these templates
404Not Found - Template slug doesn’t exist or isn’t enabled
429Too Many Requests - Rate limit exceeded
500Server Error - Internal error
Only enabled and published templates are returned by this endpoint. Archived or disabled templates require the ?archived=true query parameter.
Cache template information to improve performance. Template configurations don’t change frequently, so you can refresh this data periodically (e.g., hourly or daily).
Template slugs can be reused across different workspaces. Always combine the template slug with the workspace slug when storing or referencing templates in your system.

Authorizations

​
Authorization
string
header
required

OAuth2 access token. Include as: Authorization: Bearer {access_token}

Query Parameters

​
archived
boolean
default:false

Include archived flows when true

Response

200 - application/json

Successful response

​
data
object[]
​
included
object[]