Provision Workspace

curl --request POST \
  --url https://connect.penbox.io/v1/workspaces \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Acme Legal",
  "admin": {
    "email": "jsmith@example.com",
    "given_name": "<string>",
    "family_name": "<string>",
    "locale": "fr"
  },
  "integration": {
    "legalops": {
      "source_workspace_id": "<string>",
      "external_url": "<string>"
    }
  },
  "template_source": {
    "case_template_ids": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ]
  }
}
'

import requests

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

payload = {
    "name": "Acme Legal",
    "admin": {
        "email": "jsmith@example.com",
        "given_name": "<string>",
        "family_name": "<string>",
        "locale": "fr"
    },
    "integration": { "legalops": {
            "source_workspace_id": "<string>",
            "external_url": "<string>"
        } },
    "template_source": { "case_template_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"] }
}
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({
    name: 'Acme Legal',
    admin: {
      email: 'jsmith@example.com',
      given_name: '<string>',
      family_name: '<string>',
      locale: 'fr'
    },
    integration: {legalops: {source_workspace_id: '<string>', external_url: '<string>'}},
    template_source: {case_template_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a']}
  })
};

fetch('https://connect.penbox.io/v1/workspaces', 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/workspaces",
  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([
    'name' => 'Acme Legal',
    'admin' => [
        'email' => 'jsmith@example.com',
        'given_name' => '<string>',
        'family_name' => '<string>',
        'locale' => 'fr'
    ],
    'integration' => [
        'legalops' => [
                'source_workspace_id' => '<string>',
                'external_url' => '<string>'
        ]
    ],
    'template_source' => [
        'case_template_ids' => [
                '3c90c3cc-0d44-4b50-8888-8dd25736052a'
        ]
    ]
  ]),
  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/workspaces"

	payload := strings.NewReader("{\n  \"name\": \"Acme Legal\",\n  \"admin\": {\n    \"email\": \"jsmith@example.com\",\n    \"given_name\": \"<string>\",\n    \"family_name\": \"<string>\",\n    \"locale\": \"fr\"\n  },\n  \"integration\": {\n    \"legalops\": {\n      \"source_workspace_id\": \"<string>\",\n      \"external_url\": \"<string>\"\n    }\n  },\n  \"template_source\": {\n    \"case_template_ids\": [\n      \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n    ]\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/workspaces")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Acme Legal\",\n  \"admin\": {\n    \"email\": \"jsmith@example.com\",\n    \"given_name\": \"<string>\",\n    \"family_name\": \"<string>\",\n    \"locale\": \"fr\"\n  },\n  \"integration\": {\n    \"legalops\": {\n      \"source_workspace_id\": \"<string>\",\n      \"external_url\": \"<string>\"\n    }\n  },\n  \"template_source\": {\n    \"case_template_ids\": [\n      \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"name\": \"Acme Legal\",\n  \"admin\": {\n    \"email\": \"jsmith@example.com\",\n    \"given_name\": \"<string>\",\n    \"family_name\": \"<string>\",\n    \"locale\": \"fr\"\n  },\n  \"integration\": {\n    \"legalops\": {\n      \"source_workspace_id\": \"<string>\",\n      \"external_url\": \"<string>\"\n    }\n  },\n  \"template_source\": {\n    \"case_template_ids\": [\n      \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n    ]\n  }\n}"

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

{
  "replayed": true,
  "workspace": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "slug": "<string>"
  },
  "integration": {
    "legalops": {
      "status": "connected",
      "connected_at": "2023-11-07T05:31:56Z",
      "source_workspace_id": "<string>",
      "external_url": "<string>"
    }
  },
  "token": "pnbx_0f1e2d3c4b5a69788796a5b4c3d2e1f00112233445566778",
  "warnings": [
    "Template 3fa85f64-5717-4562-b3fc-2c963f66afa6 could not be resolved, skipped"
  ]
}

{
  "replayed": true,
  "workspace": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "slug": "<string>"
  },
  "integration": {
    "legalops": {
      "status": "connected",
      "connected_at": "2023-11-07T05:31:56Z",
      "source_workspace_id": "<string>",
      "external_url": "<string>"
    }
  },
  "token": "pnbx_0f1e2d3c4b5a69788796a5b4c3d2e1f00112233445566778",
  "warnings": [
    "Template 3fa85f64-5717-4562-b3fc-2c963f66afa6 could not be resolved, skipped"
  ]
}

{
  "errors": [
    {
      "status": "<string>",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

POST

workspaces

Provision Workspace

curl --request POST \
  --url https://connect.penbox.io/v1/workspaces \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Acme Legal",
  "admin": {
    "email": "jsmith@example.com",
    "given_name": "<string>",
    "family_name": "<string>",
    "locale": "fr"
  },
  "integration": {
    "legalops": {
      "source_workspace_id": "<string>",
      "external_url": "<string>"
    }
  },
  "template_source": {
    "case_template_ids": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ]
  }
}
'

import requests

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

payload = {
    "name": "Acme Legal",
    "admin": {
        "email": "jsmith@example.com",
        "given_name": "<string>",
        "family_name": "<string>",
        "locale": "fr"
    },
    "integration": { "legalops": {
            "source_workspace_id": "<string>",
            "external_url": "<string>"
        } },
    "template_source": { "case_template_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"] }
}
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({
    name: 'Acme Legal',
    admin: {
      email: 'jsmith@example.com',
      given_name: '<string>',
      family_name: '<string>',
      locale: 'fr'
    },
    integration: {legalops: {source_workspace_id: '<string>', external_url: '<string>'}},
    template_source: {case_template_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a']}
  })
};

fetch('https://connect.penbox.io/v1/workspaces', 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/workspaces",
  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([
    'name' => 'Acme Legal',
    'admin' => [
        'email' => 'jsmith@example.com',
        'given_name' => '<string>',
        'family_name' => '<string>',
        'locale' => 'fr'
    ],
    'integration' => [
        'legalops' => [
                'source_workspace_id' => '<string>',
                'external_url' => '<string>'
        ]
    ],
    'template_source' => [
        'case_template_ids' => [
                '3c90c3cc-0d44-4b50-8888-8dd25736052a'
        ]
    ]
  ]),
  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/workspaces"

	payload := strings.NewReader("{\n  \"name\": \"Acme Legal\",\n  \"admin\": {\n    \"email\": \"jsmith@example.com\",\n    \"given_name\": \"<string>\",\n    \"family_name\": \"<string>\",\n    \"locale\": \"fr\"\n  },\n  \"integration\": {\n    \"legalops\": {\n      \"source_workspace_id\": \"<string>\",\n      \"external_url\": \"<string>\"\n    }\n  },\n  \"template_source\": {\n    \"case_template_ids\": [\n      \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n    ]\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/workspaces")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Acme Legal\",\n  \"admin\": {\n    \"email\": \"jsmith@example.com\",\n    \"given_name\": \"<string>\",\n    \"family_name\": \"<string>\",\n    \"locale\": \"fr\"\n  },\n  \"integration\": {\n    \"legalops\": {\n      \"source_workspace_id\": \"<string>\",\n      \"external_url\": \"<string>\"\n    }\n  },\n  \"template_source\": {\n    \"case_template_ids\": [\n      \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"name\": \"Acme Legal\",\n  \"admin\": {\n    \"email\": \"jsmith@example.com\",\n    \"given_name\": \"<string>\",\n    \"family_name\": \"<string>\",\n    \"locale\": \"fr\"\n  },\n  \"integration\": {\n    \"legalops\": {\n      \"source_workspace_id\": \"<string>\",\n      \"external_url\": \"<string>\"\n    }\n  },\n  \"template_source\": {\n    \"case_template_ids\": [\n      \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n    ]\n  }\n}"

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

{
  "replayed": true,
  "workspace": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "slug": "<string>"
  },
  "integration": {
    "legalops": {
      "status": "connected",
      "connected_at": "2023-11-07T05:31:56Z",
      "source_workspace_id": "<string>",
      "external_url": "<string>"
    }
  },
  "token": "pnbx_0f1e2d3c4b5a69788796a5b4c3d2e1f00112233445566778",
  "warnings": [
    "Template 3fa85f64-5717-4562-b3fc-2c963f66afa6 could not be resolved, skipped"
  ]
}

{
  "replayed": true,
  "workspace": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "slug": "<string>"
  },
  "integration": {
    "legalops": {
      "status": "connected",
      "connected_at": "2023-11-07T05:31:56Z",
      "source_workspace_id": "<string>",
      "external_url": "<string>"
    }
  },
  "token": "pnbx_0f1e2d3c4b5a69788796a5b4c3d2e1f00112233445566778",
  "warnings": [
    "Template 3fa85f64-5717-4562-b3fc-2c963f66afa6 could not be resolved, skipped"
  ]
}

{
  "errors": [
    {
      "status": "<string>",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

Create a fully configured Penbox workspace for one of your clients, seed it with case templates, register its admins, and receive an API token scoped to that workspace — in a single call. For the end-to-end flow, see Onboard a Client.

Workspace provisioning must be enabled on your account — talk to Penbox. A token without it is rejected with a 401.

Two silent admins are created. The admin in the payload is your client’s. Penbox also adds your own support account, read from the support_email configured once on your partner workspace — it is never sent here. Without one, the call still succeeds and says so in warnings.

The token is returned exactly once, in the 201 response that creates the workspace. Penbox stores nothing but its hash — persist it before you do anything else.

Idempotency

The call is idempotent on integration.legalops.source_workspace_id: one Penbox workspace per workspace on your side. Use the status code to tell a creation from a replay:

Status	Meaning	`token`
`201`	The workspace was created	Present, once
`200`	The workspace already existed	Absent

Provisioning never fails halfway: an optional step that did not complete is reported in the warnings array, not as an error.

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

name

string

required

Workspace name. The slug is derived from it, with a numeric suffix when that slug is already taken.

Required string length: 3 - 64

Example:

"Acme Legal"

admin

object

required

The client's administrator. Created as a silent member: Penbox never emails them.

Show child attributes

integration

object

required

Identifies the client workspace on your side. This is what makes the call idempotent.

Show child attributes

template_source

object

Case templates to copy into the new workspace.

Show child attributes

Response

A workspace already exists for this source_workspace_id. Same payload, without token.

replayed

boolean

False when this call created the workspace, true when it returned one that already existed.

workspace

object

The Penbox workspace

Show child attributes

integration

object

The link back to the workspace on your side

Show child attributes

token

string

API token scoped to the new workspace. Returned exactly ONCE, in the 201 that created it: Penbox stores only its hash and can never show it again. Absent from a replay.

Example:

"pnbx_0f1e2d3c4b5a69788796a5b4c3d2e1f00112233445566778"

warnings

string[]

Optional steps that did not complete. The workspace is fully created either way — these are not errors. Absent when there is nothing to report.

Example:

[
  "Template 3fa85f64-5717-4562-b3fc-2c963f66afa6 could not be resolved, skipped"
]

API Reference

Workspaces

Cases

Tasks

Case Templates

Forms

Form Templates

Attachments

Document Intelligence

Signatures

Previous API version

Provision Workspace

Idempotency

Authorizations

Body

Response

​Idempotency

Authorizations

Body

Response

Idempotency