Skip to main content
POST
/
workspaces
Create a workspace
curl --request POST \
  --url https://api.retrac.co/workspaces \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "slug": "<string>",
  "logo": "<string>"
}
'
{
  "id": "<string>",
  "name": "<string>",
  "slug": "<string>",
  "logo": null,
  "usage": 123,
  "usageLimit": 123,
  "itemsUsage": 123,
  "itemsLimit": 123,
  "suppliersUsage": 123,
  "suppliersLimit": 123,
  "locationsUsage": 123,
  "locationsLimit": 123,
  "defaultLocationId": null,
  "defaultCurrency": "<string>",
  "invoiceNumberPrefix": "<string>",
  "defaultTaxPercent": 50,
  "defaultTaxIncluded": true,
  "defaultInvoiceDueDays": 182,
  "invoicingBusinessName": null,
  "invoicingBrandColor": null,
  "invoicingEmail": null,
  "invoicingAddress": null,
  "defaultInvoiceSourceLocationId": null,
  "defaultTransferFromLocationId": null,
  "defaultMarkupPercent": 500,
  "tagsLimit": 123,
  "usersLimit": 123,
  "stripeId": "<string>",
  "billingCycleStart": 123,
  "createdAt": "<string>",
  "trialEndsAt": "<string>",
  "users": [
    {}
  ],
  "inviteCode": "<string>",
  "ssoEmailDomain": "<string>",
  "ssoEnforcedAt": "<string>",
  "locationAccess": {
    "restricted": true,
    "locations": [
      {
        "locationId": "<string>"
      }
    ]
  },
  "memberPermissions": {
    "capabilities": {},
    "profile": {
      "builtinTemplateKey": "<string>",
      "customTemplateId": "<string>",
      "customTemplateName": "<string>",
      "overrideCount": 123,
      "permissionsManaged": true,
      "legacyUnrestricted": true
    }
  }
}

Authorizations

Authorization
string
header
required

Bearer API key from Settings → API Keys. Use restricted keys (prefix retrac_) with the minimum scopes required.

Body

application/json
name
string
required
Required string length: 1 - 32
slug
string
required
Required string length: 3 - 48

Response

The created workspace

id
string
required

The unique ID of the workspace.

name
string
required

The name of the workspace.

slug
string
required

The slug of the workspace.

logo
string | null
required

The logo of the workspace.

usage
number
required

The usage of the workspace.

usageLimit
number
required

The usage limit of the workspace.

itemsUsage
number
required

The items usage of the workspace.

itemsLimit
number
required

The items limit of the workspace.

suppliersUsage
number
required

The suppliers usage of the workspace.

suppliersLimit
number
required

The suppliers limit of the workspace.

locationsUsage
number
required

The locations usage of the workspace.

locationsLimit
number
required

The locations limit of the workspace.

defaultLocationId
string | null
required

The ID of the default 'Inventory' location.

defaultCurrency
string
required

Default currency for jobs and monetary displays.

Required string length: 3
invoiceNumberPrefix
string
required

Prefix used when generating invoice numbers.

Required string length: 1 - 12
defaultTaxPercent
number
required

Default tax rate applied when closing jobs.

Required range: 0 <= x <= 100
defaultTaxIncluded
boolean
required

When true, line prices include tax; when false, tax is added on top.

defaultInvoiceDueDays
integer
required

Days after creation when new invoices are due by default (0 = no default due date).

Required range: 0 <= x <= 365
invoicingBusinessName
string | null
required

Business name shown on invoices and estimates.

invoicingBrandColor
string | null
required

Accent color used on client-facing billing documents.

invoicingEmail
string | null
required

Contact email shown on billing documents.

invoicingAddress
string | null
required

Business address shown on billing documents.

defaultInvoiceSourceLocationId
string | null
required

Default source location when closing jobs.

defaultTransferFromLocationId
string | null
required

Default source location when creating transfers.

defaultLocationType
enum<string>
required

Default type for newly created locations.

Available options:
warehouse,
van,
truck,
site,
other
defaultMarkupPercent
number | null
required

Default markup percentage applied from unit cost to sell price.

Required range: 0 <= x <= 1000
tagsLimit
number
required

The tags limit of the workspace.

usersLimit
number
required

The users limit of the workspace.

plan
enum<string>
required

The plan of the workspace.

Available options:
free,
pro,
business,
advanced,
business plus,
business extra,
business max,
enterprise
stripeId
string | null
required

The Stripe ID of the workspace.

billingCycleStart
number
required

The date and time when the billing cycle starts for the workspace.

createdAt
string
required

The date and time when the workspace was created.

trialEndsAt
string | null
required

When the workspace billing trial ends, if applicable.

users
object[]
required

The role of the authenticated user in the workspace.

inviteCode
string | null
required

The invite code of the workspace.

ssoEmailDomain
string | null
required
ssoEnforcedAt
string | null
required
locationAccess
object

Location access for the authenticated member.

memberPermissions
object

Effective member capabilities for the authenticated user.