> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ruddr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a client

A person or organization using your services. All projects are tied to a client.


## OpenAPI

````yaml openapi.json POST /clients
openapi: 3.1.0
info:
  title: Ruddr API
  version: '1.0'
  license:
    name: Proprietary
    url: https://www.ruddr.com/master-subscription-agreement
servers:
  - url: https://www.ruddr.io/api/workspace
security:
  - bearerAuth: []
tags:
  - name: Allocations
    description: Manage resource allocations for scheduling team members to projects.
  - name: Availability Periods
    description: Manage member availability periods for capacity planning.
  - name: Business Units
    description: >-
      Manage business units for organizing invoice settings and grouping clients
      and projects.
  - name: Client Roles
    description: Manage client roles and their billing terms.
  - name: Client Tags
    description: Manage tags for categorizing clients.
  - name: Clients
    description: Manage clients and their billing settings.
  - name: Companies
    description: Manage companies in the CRM pipeline.
  - name: Company Spend Tiers
    description: Manage spend tier classifications for companies.
  - name: Company Types
    description: Manage type classifications for companies.
  - name: Contact Tags
    description: Manage tags for categorizing contacts.
  - name: Contacts
    description: Manage contacts associated with clients, companies, and opportunities.
  - name: Cost Periods
    description: Manage member cost rate periods for profitability tracking.
  - name: Credit Notes
    description: View credit notes issued against invoices.
  - name: Disciplines
    description: Manage disciplines for classifying member skill areas.
  - name: Exchange Rate
    description: Get exchange rates for multi-currency workspaces.
  - name: Exchange Rate Periods
    description: Manage custom exchange rate periods for currency conversion.
  - name: Expense Categories
    description: Manage expense categories for tracking and reporting.
  - name: Expense Items
    description: Manage individual expense line items.
  - name: Expense Reports
    description: Manage expense reports submitted by members.
  - name: Holiday Schedules
    description: Manage holiday schedules for capacity and availability planning.
  - name: Holidays
    description: Manage individual holidays within holiday schedules.
  - name: Industries
    description: Manage industry classifications for clients and companies.
  - name: Invoice Items
    description: Manage invoice line item types for billing.
  - name: Invoices
    description: View invoices and their line items.
  - name: Job Titles
    description: Manage job title classifications for members.
  - name: Locations
    description: Manage office locations for members and projects.
  - name: Member Certifications
    description: Manage certification types that can be assigned to members.
  - name: Member Levels
    description: Manage member level classifications for career tracking.
  - name: Member Tags
    description: Manage tags for categorizing members.
  - name: Members
    description: Manage workspace members and their profiles.
  - name: Opportunities
    description: Manage sales opportunities in the CRM pipeline.
  - name: Opportunity Pipelines
    description: Manage pipelines for tracking opportunity stages.
  - name: Opportunity Lead Sources
    description: Manage lead source classifications for opportunities.
  - name: Opportunity Stages
    description: Manage pipeline stage definitions for opportunities.
  - name: Opportunity Tags
    description: Manage tags for categorizing opportunities.
  - name: Opportunity Types
    description: Manage type classifications for opportunities.
  - name: Payment Methods
    description: Manage payment method options for invoices.
  - name: Payments
    description: View payments received against invoices.
  - name: Pipeline Activities
    description: >-
      Manage pipeline activities associated with companies, contacts, members,
      and opportunities.
  - name: Pipeline Activity Types
    description: Manage activity type classifications for pipeline activities.
  - name: Practices
    description: Manage practice area classifications for organizing projects and members.
  - name: Project Budget Expenses
    description: Manage expense budget line items on projects.
  - name: Project Budget Other Items
    description: Manage other budget line items on projects.
  - name: Project Budget Product Items
    description: Manage product budget line items on projects.
  - name: Project Budget Service Items
    description: Manage additional service budget line items on projects.
  - name: Project Expenses
    description: Manage project-level expense line items.
  - name: Project Groups
    description: View project groups for organizing related projects.
  - name: Project Health Reports
    description: Manage project health status reports.
  - name: Project Invoice Milestones
    description: Manage invoice milestones for fixed-fee project billing.
  - name: Project Members
    description: Manage team member assignments on projects.
  - name: Project Monthly Budget Expenses
    description: Manage monthly expense budget line items on projects.
  - name: Project Monthly Budget Other Items
    description: Manage monthly other budget line items on projects.
  - name: Project Monthly Budget Product Items
    description: Manage monthly product budget line items on projects.
  - name: Project Monthly Budget Service Items
    description: Manage monthly additional service budget line items on projects.
  - name: Project Other Items
    description: Manage project-level other item line items.
  - name: Project Product Items
    description: Manage project-level product line items.
  - name: Project Revenue Adjustments
    description: Manage earned revenue adjustments for projects.
  - name: Project Revenue Recognition Entries
    description: Manage revenue recognition entries for projects.
  - name: Project Roles
    description: Manage roles defined on projects for billing and staffing.
  - name: Project Service Items
    description: Manage project-level additional service line items.
  - name: Project Tags
    description: Manage tags for categorizing projects.
  - name: Project Tasks
    description: Manage tasks on projects for time tracking and planning.
  - name: Project Types
    description: Manage type classifications for projects.
  - name: Projects
    description: Manage projects and their settings.
  - name: Resource Placeholders
    description: Manage placeholder resources for allocation planning.
  - name: Security Roles
    description: View security roles for assigning member permissions.
  - name: Skills
    description: Manage skill classifications for members and resource planning.
  - name: Task Categories
    description: Manage task category classifications for project tasks.
  - name: Task Tags
    description: Manage tags for categorizing project tasks.
  - name: Task Templates
    description: Manage reusable task templates for projects.
  - name: Tax Rates
    description: Manage tax rates for invoicing.
  - name: Time Entries
    description: Manage time entries for tracking hours on projects.
  - name: Time Off Types
    description: Manage time off type classifications.
  - name: Timesheet Attestations
    description: Manage attestation statements members sign when submitting timesheets.
  - name: Timesheets
    description: Manage timesheet submissions for tracking hours across a period.
  - name: Utilization Target Periods
    description: Manage member utilization target periods for capacity planning.
  - name: Workspace Roles
    description: Manage workspace-level roles for billing rate configuration.
paths:
  /clients:
    post:
      tags:
        - Clients
      summary: Create a client
      operationId: create-a-client
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                key:
                  type: string
                  description: >-
                    The URL-friendly slug for the client. Will be autogenerated
                    from `name` if not provided. Max 255 characters.
                name:
                  type: string
                  description: The name of the client. Max 255 characters.
                code:
                  type:
                    - string
                    - 'null'
                  description: The client code. Max 255 characters.
                currency:
                  type: string
                  description: >-
                    The 3-letter currency code associated with the client.
                    Defaults to the workspace currency if not supplied.
                notes:
                  type:
                    - string
                    - 'null'
                  description: Notes associated with the client. Max 5000 characters.
                emails:
                  type: array
                  items:
                    type: string
                  description: Email addresses used for invoicing the client.
                streetAddress:
                  type:
                    - string
                    - 'null'
                  description: >-
                    The street address of the client used for invoicing. Max
                    5000 characters.
                invoiceDetailsSource:
                  type: string
                  description: >-
                    The source of invoice details. Defaults to `workspace`. When
                    `workspace` or `business_unit`, the `invoicePaymentTermId`,
                    `invoiceSubject`, `invoiceNotes`, `invoiceEmailSubject`, and
                    `invoiceEmailBody` values are inherited.
                  enum:
                    - workspace
                    - custom
                    - business_unit
                invoiceSubject:
                  type:
                    - string
                    - 'null'
                  description: >-
                    The subject line used on invoices for this client. Max 255
                    characters.
                invoiceNotes:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Notes included on invoices for this client. Max 5000
                    characters.
                invoiceEmailSubject:
                  type:
                    - string
                    - 'null'
                  description: >-
                    The email subject line used when sending invoices for this
                    client. Max 255 characters.
                invoiceEmailBody:
                  type:
                    - string
                    - 'null'
                  description: >-
                    The email body used when sending invoices for this client.
                    Max 5000 characters.
                recordStatusId:
                  type: string
                  description: The record status of the client. Defaults to `active`.
                  enum:
                    - active
                    - archived
                ownerId:
                  type:
                    - string
                    - 'null'
                  description: The member ID (`uuid`) of the owner of this client.
                practiceId:
                  type:
                    - string
                    - 'null'
                  description: >-
                    The practice ID (`uuid`) of the practice associated with
                    this client.
                industryId:
                  type:
                    - string
                    - 'null'
                  description: >-
                    The industry ID (`uuid`) of the industry associated with
                    this client.
                locationId:
                  type:
                    - string
                    - 'null'
                  description: >-
                    The location ID (`uuid`) of the location associated with
                    this client.
                tagIds:
                  type: array
                  description: >-
                    A list of client tag IDs (`uuid`) to associate with this
                    client.
                  items:
                    type: string
                invoicePaymentTermId:
                  type: string
                  description: The payment term ID (`uuid`) used for invoicing the client.
                salesRepresentativeId:
                  type:
                    - string
                    - 'null'
                  description: >-
                    The member ID (`uuid`) of the sales representative for this
                    client.
                businessUnitId:
                  type:
                    - string
                    - 'null'
                  description: >-
                    The business unit ID (`uuid`) of the business unit
                    associated with this client.
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
              examples:
                Result:
                  value:
                    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
                    industry:
                      id: bc52e68a-96d9-46bd-881c-bda8d5e07053
                      name: Technology
                    location:
                      id: ae469b03-51f3-47c2-be12-a319e0ce7cd8
                      name: New York
                    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
                    integrations:
                      - type: xero
                        connectionId: 9d2f6b1a-4c83-4e57-bf09-1a6d3e8c20b4
                        externalId: 5e1a9c47-2b86-4d30-9f12-7a4c8e3b50d9
                      - type: qbo
                        connectionId: c4a7e2f9-83b1-4d65-9e07-2f1b6a4c80d3
                        externalId: '142'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                Validation:
                  value:
                    status: 400
                    message: >-
                      There was a problem processing your request. See errors
                      for more details.
                    errors:
                      - '''name'' is required'
                InvalidData:
                  value:
                    status: 400
                    message: >-
                      'ownerId' 'fc15c882-673c-4482-a665-9a7a22bb7530' does not
                      match a valid member.
      deprecated: false
components:
  schemas:
    Client:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the object.
        key:
          type: string
          description: The URL-friendly slug for the client.
        name:
          type: string
          description: The name of the client.
        code:
          type:
            - string
            - 'null'
          description: The client code.
        currency:
          type: string
          description: The 3-letter currency code associated with the client.
        notes:
          type:
            - string
            - 'null'
          description: Notes associated with the client.
        emails:
          type: array
          items:
            type: string
          description: Email addresses used for invoicing the client.
        streetAddress:
          type:
            - string
            - 'null'
          description: The street address of the client used for invoicing.
        invoiceDetailsSource:
          type: string
          description: >-
            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.
          enum:
            - workspace
            - custom
            - business_unit
        invoiceSubject:
          type:
            - string
            - 'null'
          description: The subject line used on invoices for this client.
        invoiceNotes:
          type:
            - string
            - 'null'
          description: Notes included on invoices for this client.
        invoiceEmailSubject:
          type:
            - string
            - 'null'
          description: The email subject line used when sending invoices for this client.
        invoiceEmailBody:
          type:
            - string
            - 'null'
          description: The email body used when sending invoices for this client.
        isInternal:
          type: boolean
          description: >-
            Indicates whether this is the workspace's internal client. This
            client is auto-created during workspace setup.
        recordStatusId:
          type: string
          description: The record status of the client.
          enum:
            - active
            - archived
        createdAt:
          type: string
          format: date-time
          description: The timestamp when the object was created.
        owner:
          type:
            - object
            - 'null'
          description: The member who owns this client.
          properties:
            id:
              type: string
              description: The unique identifier for the object.
            name:
              type: string
              description: The name of the member.
        practice:
          type:
            - object
            - 'null'
          description: The practice associated with this client.
          properties:
            id:
              type: string
              description: The unique identifier for the object.
            name:
              type: string
              description: The name of the practice.
        industry:
          type:
            - object
            - 'null'
          description: The industry associated with this client.
          properties:
            id:
              type: string
              description: The unique identifier for the object.
            name:
              type: string
              description: The name of the industry.
        location:
          type:
            - object
            - 'null'
          description: The location associated with this client.
          properties:
            id:
              type: string
              description: The unique identifier for the object.
            name:
              type: string
              description: The name of the location.
        tags:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: The unique identifier for the object.
              name:
                type: string
                description: The name of the tag.
          description: The tags associated with this client.
        invoicePaymentTerm:
          type:
            - object
            - 'null'
          description: The payment term used for invoicing this client.
          properties:
            id:
              type: string
              description: The unique identifier for the object.
            name:
              type: string
              description: The name of the payment term.
        salesRepresentative:
          type:
            - object
            - 'null'
          description: The sales representative for this client.
          properties:
            id:
              type: string
              description: The unique identifier for the object.
            name:
              type: string
              description: The name of the member.
        useWorkspaceInvoiceDetails:
          type: boolean
          deprecated: true
          description: >-
            A legacy read-only field indicating whether the client uses
            workspace-level invoice details. Use `invoiceDetailsSource` instead.
        businessUnit:
          type:
            - object
            - 'null'
          description: The business unit associated with this client.
          properties:
            id:
              type: string
              description: The unique identifier for the object.
            name:
              type: string
              description: The name of the business unit.
        integrations:
          type: array
          description: >-
            The accounting integration mappings for this client. Each entry ties
            the client to a record in an external accounting system. Empty when
            no integrations are configured.
          items:
            type: object
            properties:
              type:
                type: string
                description: The accounting integration provider.
                enum:
                  - xero
                  - qbo
              connectionId:
                type: string
                description: >-
                  The Ruddr accounting connection ID associated with this
                  mapping.
              externalId:
                type: string
                description: >-
                  The identifier of the corresponding record in the external
                  accounting system.
    ValidationErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: The HTTP status code.
        message:
          type: string
          description: A human-readable error message.
        errors:
          type: array
          description: A list of validation error messages.
          items:
            type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````