Skip to content
Internal preview — Billtyme does not issue or send invoices yet.See what's included
Billtyme
Esc
↑↓navigate↵open⌘Jpreview

Create a company

Creates a legal invoice sender inside the authenticated account. The WorkOS organization is always derived from the verified token.

POST/v1/companies
Authorization
AuthorizationBearer token (JWT) · headerrequired
WorkOS AuthKit user, service, or agent access token
Header parameters
idempotency-keystringrequired
min length 8 · max length 255 · matches ^[\u0021-\u007E]+$
Request body
requiredapplication/json
addressobjectrequired
Show properties
citystringrequired
min length 1 · max length 120
country_codestringrequired
matches ^[A-Z]{2}$
line_1stringrequired
min length 1 · max length 200
line_2string
max length 200
postal_codestringrequired
min length 1 · max length 32
regionstring
max length 120
default_currencystringrequired
matches ^[A-Z]{3}$
default_languagestring
matches ^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$ · default: "en"
default_payment_terms_daysinteger
min 0 · max 365 · default: 30
emailstring<email>
external_referencestring
min length 1 · max length 255
identifiersobject[]
max items 20 · default: []
Show properties
Array of object
country_codestring
matches ^[A-Z]{2}$
schemestringrequired
matches ^[a-z][a-z0-9._-]{0,63}$
valuestringrequired
min length 1 · max length 200
legal_namestringrequired
min length 1 · max length 200
trading_namestring
min length 1 · max length 200
Responses
201Company created or idempotently replayed
addressobjectrequired
Show properties
citystringrequired
min length 1 · max length 120
country_codestringrequired
matches ^[A-Z]{2}$
line_1stringrequired
min length 1 · max length 200
line_2string
max length 200
postal_codestringrequired
min length 1 · max length 32
regionstring
max length 120
archived_atstring<date-time> | nullrequired
created_atstring<date-time>required
default_currencystringrequired
matches ^[A-Z]{3}$
default_languagestring
matches ^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$ · default: "en"
default_payment_terms_daysinteger
min 0 · max 365 · default: 30
emailstring<email>
external_referencestring
min length 1 · max length 255
idstring<uuid>required
identifiersobject[]
max items 20 · default: []
Show properties
Array of object
country_codestring
matches ^[A-Z]{2}$
schemestringrequired
matches ^[a-z][a-z0-9._-]{0,63}$
valuestringrequired
min length 1 · max length 200
legal_namestringrequired
min length 1 · max length 200
trading_namestring
min length 1 · max length 200
updated_atstring<date-time>required
versionintegerrequired
400Malformed request
errorobjectrequired
Show properties
codestringrequired
detailsobject[]
Show properties
Array of object
messagestringrequired
pathstringrequired
messagestringrequired
request_idstringrequired
401Authentication failed
errorobjectrequired
Show properties
codestringrequired
detailsobject[]
Show properties
Array of object
messagestringrequired
pathstringrequired
messagestringrequired
request_idstringrequired
403Permission denied
errorobjectrequired
Show properties
codestringrequired
detailsobject[]
Show properties
Array of object
messagestringrequired
pathstringrequired
messagestringrequired
request_idstringrequired
409Request conflict
errorobjectrequired
Show properties
codestringrequired
detailsobject[]
Show properties
Array of object
messagestringrequired
pathstringrequired
messagestringrequired
request_idstringrequired
413Request body is too large
errorobjectrequired
Show properties
codestringrequired
detailsobject[]
Show properties
Array of object
messagestringrequired
pathstringrequired
messagestringrequired
request_idstringrequired
415Unsupported media type
errorobjectrequired
Show properties
codestringrequired
detailsobject[]
Show properties
Array of object
messagestringrequired
pathstringrequired
messagestringrequired
request_idstringrequired
422Request validation failed
errorobjectrequired
Show properties
codestringrequired
detailsobject[]
Show properties
Array of object
messagestringrequired
pathstringrequired
messagestringrequired
request_idstringrequired
500Unexpected server error
errorobjectrequired
Show properties
codestringrequired
detailsobject[]
Show properties
Array of object
messagestringrequired
pathstringrequired
messagestringrequired
request_idstringrequired
Request
curl -X POST "/v1/companies" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "idempotency-key: stringst" \
  -H "Content-Type: application/json" \
  -d '{
  "address": {
    "city": "string",
    "country_code": "string",
    "line_1": "string",
    "line_2": "string",
    "postal_code": "string",
    "region": "string"
  },
  "default_currency": "string",
  "default_language": "en",
  "default_payment_terms_days": 30,
  "email": "user@example.com",
  "external_reference": "string",
  "identifiers": [],
  "legal_name": "string",
  "trading_name": "string"
}'
Response
{
  "address": {
    "city": "string",
    "country_code": "string",
    "line_1": "string",
    "line_2": "string",
    "postal_code": "string",
    "region": "string"
  },
  "archived_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "default_currency": "string",
  "default_language": "en",
  "default_payment_terms_days": 30,
  "email": "user@example.com",
  "external_reference": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "identifiers": [],
  "legal_name": "string",
  "trading_name": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0
}