Provision Workspace (Partners)

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 the client’s admin, and receive an API token scoped to that workspace — in a single call.

This endpoint is reserved for partner integrations. A regular API token is rejected with a 401. Talk to Penbox to have your own workspace enabled as a partner.

The token is returned exactly once. It appears only in the 201 response that creates the workspace, and Penbox stores nothing but its hash — it can never be retrieved again. Persist it before you do anything else with the response.

Idempotency

The call is idempotent on integration.legalops.source_workspace_id: one Penbox workspace per workspace on your side. Calling it again with the same source_workspace_id returns the workspace that already exists, with a 200 instead of a 201 and without a token. Use the status code to tell the two apart:

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

Partial success

Provisioning never fails halfway: if an optional step does not complete, the workspace is still created and the response carries a warnings array describing what was skipped — a case template that could not be copied, for instance. Log the warnings — they are not errors.

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

Case Templates

Forms

Form Templates

Attachments

Document Intelligence

Signatures

Previous API version

Idempotency

Partial success

Authorizations

Body

Response

​Idempotency

​Partial success

Authorizations

Body

Response

Idempotency

Partial success