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

Create a customer

Creates a billing customer belonging to one legal-sender company. The company path is included in idempotency semantics.

POST/v1/companies/{company_id}/customers
Authorization
AuthorizationBearer token (JWT) · headerrequired
WorkOS AuthKit user, service, or agent access token
Path parameters
company_idstring<uuid>required
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
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
namestringrequired
min length 1 · max length 200
Responses
201Customer 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
company_idstring<uuid>required
created_atstring<date-time>required
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
namestringrequired
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
404Resource not found
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/497f6eca-6276-4993-bfeb-53cbbbba6f08/customers" \
  -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"
  },
  "email": "user@example.com",
  "external_reference": "string",
  "identifiers": [],
  "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",
  "company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf",
  "created_at": "2019-08-24T14:15:22Z",
  "email": "user@example.com",
  "external_reference": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "identifiers": [],
  "name": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0
}