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

{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "companies",
      "attributes": {
        "name": "<string>",
        "slug": "<string>",
        "logo": "<string>",
        "colors": {
          "primary": "<string>",
          "secondary": "<string>"
        }
      }
    }
  ]
}
Retrieve all Penbox workspaces (API: companies) that the authenticated user has authorized your application to access.
In the API, workspaces are referred to as companies. This is the technical term used in all endpoints and parameters.
curl -X GET 'https://connect.penbox.io/v1/companies' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

​
Response Fields

FieldTypeDescription
idstringWorkspace UUID
created_atstringISO 8601 creation timestamp
slugstringUnique workspace identifier (URL-safe)
namestringWorkspace display name

​
Workspace Slug

The slug is a URL-safe, unique identifier for the workspace. It’s used in API calls to specify which workspace you want to interact with. Slug format:
  • Lowercase letters, numbers, and hyphens
  • No spaces or special characters
  • Unique across all Penbox workspaces
Examples:
  • acme-corp
  • my-company-123
  • law-firm-llp

​
Use Cases

​
Multi-Workspace Support

If a user has authorized multiple Penbox workspaces, this endpoint returns all of them: 
// Get available workspaces
const workspaces = await fetch('https://connect.penbox.io/v1/companies', {
  headers: { 'Authorization': `Bearer ${accessToken}` }
}).then(r => r.json()); // Returns array directly

// Let user select a workspace or use the first one
const selectedWorkspace = workspaces[0];

// Create form in that workspace
await fetch('https://connect.penbox.io/v1/requests', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    company: { slug: selectedWorkspace.slug },
    flow: { slug: 'onboarding-form' },
    user: { email: '[email protected]' }
  })
});

​
Display Workspace Info

Use workspace information to customize your UI: 
const workspace = workspaces[0];

document.getElementById('app-title').textContent = workspace.name;
console.log('Workspace ID:', workspace.id);
console.log('Workspace slug:', workspace.slug);

​
Workspace Mapping

If your application supports multiple Penbox workspaces per user: 
// Store workspace mapping
const workspaceMapping = {
  [userAccountId]: {
    workspaces: workspaces.map(w => ({
      id: w.id,
      slug: w.slug,
      name: w.name
    }))
  }
};

// Later, create forms in specific workspace
function createForm(workspaceSlug, templateSlug, userData) {
  return fetch('https://connect.penbox.io/v1/requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      company: { slug: workspaceSlug },
      flow: { slug: templateSlug },
      user: userData
    })
  });
}

​
Response Codes

CodeDescription
200Success - Returns list of workspaces
401Unauthorized - Invalid or expired access token
403Forbidden - Token doesn’t have required permissions
429Too Many Requests - Rate limit exceeded
500Server Error - Internal error
If a user has authorized your application for multiple workspaces, this endpoint returns all of them. The access token grants access to all authorized workspaces.
Cache the workspace list to avoid unnecessary API calls. Workspaces rarely change, so you can refresh this data infrequently (e.g., once per session or when explicitly requested).
If the access token is revoked or expires, this endpoint will return a 401 error. Always handle token refresh logic properly.

Authorizations

​
Authorization
string
header
required

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

Response

200 - application/json

Successful response

​
data
object[]