Skip to main content
POST
/
clients
Create a client
curl --request POST \
  --url https://www.ruddr.io/api/workspace/clients \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "key": "<string>",
  "code": "<string>",
  "currency": "<string>",
  "notes": "<string>",
  "emails": [
    "<string>"
  ],
  "streetAddress": "<string>",
  "invoiceDetailsSource": "workspace",
  "invoiceSubject": "<string>",
  "invoiceNotes": "<string>",
  "invoiceEmailSubject": "<string>",
  "invoiceEmailBody": "<string>",
  "recordStatusId": "active",
  "ownerId": "<string>",
  "practiceId": "<string>",
  "tagIds": [
    "<string>"
  ],
  "invoicePaymentTermId": "<string>",
  "salesRepresentativeId": "<string>",
  "businessUnitId": "<string>"
}
'
{
  "id": "4d7a1c3e-8f2b-4a90-b5d6-e9c1f0a82d47",
  "key": "acme-corp",
  "name": "Acme Corp",
  "code": "ACM-001",
  "currency": "USD",
  "notes": "Key enterprise client.",
  "emails": [
    "billing@acmecorp.com"
  ],
  "streetAddress": "100 Market St, Suite 500",
  "invoiceDetailsSource": "custom",
  "invoiceSubject": "Invoice for professional services",
  "invoiceNotes": "Payment due within 30 days of receipt.",
  "invoiceEmailSubject": "Invoice from Ruddr",
  "invoiceEmailBody": "Please find your invoice attached.",
  "isInternal": false,
  "recordStatusId": "active",
  "createdAt": "2025-01-15T20:47:03.284Z",
  "owner": {
    "id": "e5c8a2f4-3d19-4b76-a0e7-9f1d6c4b28a3",
    "name": "Jane Smith"
  },
  "practice": {
    "id": "b82e4f61-a9c3-4d17-8e05-6f3b2a7d90c1",
    "name": "Consulting"
  },
  "tags": [
    {
      "id": "91d4e7a3-f826-4c10-b5a8-0e3d9c1f72b4",
      "name": "Enterprise"
    }
  ],
  "invoicePaymentTerm": {
    "id": "7a3f1d8e-c249-4b65-91d7-e0a4f8b2c603",
    "name": "Net 30"
  },
  "salesRepresentative": {
    "id": "c6f2b081-d47a-4e93-a8d5-3e1c7f9a204b",
    "name": "John Davis"
  },
  "useWorkspaceInvoiceDetails": false,
  "businessUnit": {
    "id": "2e8d5a7c-f314-4b09-96e1-a0c3d8f4b172",
    "name": "North America"
  }
}
A person or organization using your services. All projects are tied to a client.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
name
string
required

The name of the client. Max 255 characters.

​
key
string

The URL-friendly slug for the client. Will be autogenerated from name if not provided. Max 255 characters.

​
code
string | null

The client code. Max 255 characters.

​
currency
string

The 3-letter currency code associated with the client. Defaults to the workspace currency if not supplied.

​
notes
string | null

Notes associated with the client. Max 5000 characters.

​
emails
string[]

Email addresses used for invoicing the client.

​
streetAddress
string | null

The street address of the client used for invoicing. Max 5000 characters.

​
invoiceDetailsSource
enum<string>

The source of invoice details. Defaults to workspace. When workspace or business_unit, the invoicePaymentTermId, invoiceSubject, invoiceNotes, invoiceEmailSubject, and invoiceEmailBody values are inherited.

Available options:
workspace,
custom,
business_unit
​
invoiceSubject
string | null

The subject line used on invoices for this client. Max 255 characters.

​
invoiceNotes
string | null

Notes included on invoices for this client. Max 5000 characters.

​
invoiceEmailSubject
string | null

The email subject line used when sending invoices for this client. Max 255 characters.

​
invoiceEmailBody
string | null

The email body used when sending invoices for this client. Max 5000 characters.

​
recordStatusId
enum<string>

The record status of the client. Defaults to active.

Available options:
active,
archived
​
ownerId
string | null

The member ID (uuid) of the owner of this client.

​
practiceId
string | null

The practice ID (uuid) of the practice associated with this client.

​
tagIds
string[]

A list of client tag IDs (uuid) to associate with this client.

​
invoicePaymentTermId
string

The payment term ID (uuid) used for invoicing the client.

​
salesRepresentativeId
string | null

The member ID (uuid) of the sales representative for this client.

​
businessUnitId
string | null

The business unit ID (uuid) of the business unit associated with this client.

Response

200

​
id
string

The unique identifier for the object.

​
key
string

The URL-friendly slug for the client.

​
name
string

The name of the client.

​
code
string | null

The client code.

​
currency
string

The 3-letter currency code associated with the client.

​
notes
string | null

Notes associated with the client.

​
emails
string[]

Email addresses used for invoicing the client.

​
streetAddress
string | null

The street address of the client used for invoicing.

​
invoiceDetailsSource
enum<string>

The source of invoice details for this client. Determines whether invoice settings are inherited from the workspace, the assigned business unit, or configured at the client level.

Available options:
workspace,
custom,
business_unit
​
invoiceSubject
string | null

The subject line used on invoices for this client.

​
invoiceNotes
string | null

Notes included on invoices for this client.

​
invoiceEmailSubject
string | null

The email subject line used when sending invoices for this client.

​
invoiceEmailBody
string | null

The email body used when sending invoices for this client.

​
isInternal
boolean

Indicates whether this is the workspace's internal client. This client is auto-created during workspace setup.

​
recordStatusId
enum<string>

The record status of the client.

Available options:
active,
archived
​
createdAt
string<date-time>

The timestamp when the object was created.

​
owner
object

The member who owns this client.

​
practice
object

The practice associated with this client.

​
tags
object[]

The tags associated with this client.

​
invoicePaymentTerm
object

The payment term used for invoicing this client.

​
salesRepresentative
object

The sales representative for this client.

​
useWorkspaceInvoiceDetails
boolean
deprecated

A legacy read-only field indicating whether the client uses workspace-level invoice details. Use invoiceDetailsSource instead.

​
businessUnit
object

The business unit associated with this client.