Skip to content
Leadtime
English
EnglishDeutschNot translated
Esc
↑↓navigate↵open⌘Jpreview

Create organization

Creates a new organization (external business partner) in your workspace.

What are Organizations? Organizations represent external business partners like customers, suppliers, partners, or competitors. They serve as the foundation for managing external projects, contacts, invoices, and business relationships.

Required fields:

  • name: Full company name (e.g., “Acme Corporation”)
  • type: Organization type (Customer, Prospect, Supplier, Partner, etc.)
  • color: Hex color code for visual identification (e.g., “#FF5733”)

Optional fields:

  • shortName: 3-5 character abbreviation (auto-generated if not provided)

  • icon: Icon identifier for visual representation

  • legalForm: Legal company form (e.g., “GmbH”, “AG”, “LLC”)

  • startOfCollaboration: Date when business relationship started (ISO date format: YYYY-MM-DD)

  • Contact information: Address fields, phone, fax, email, website

  • Legal information: Tax number, registration number, registration court

  • Invoice settings: Hourly rate, payment terms, reminder fees, interest rates

  • Document settings: Table of contents, title page, heading style

  • customFields: Values keyed by configured organization custom-field IDs. Values must match their definition types. Custom fields store typed data; they do not create native relationships or behavior.

Uploading a logo:

  1. First, call POST /api/public/workspace/upload to upload the logo file
  2. The upload endpoint returns a file ID (UUID)
  3. Use that file ID in the logoId field when creating the organization

Auto-generated fields:

  • If shortName is not provided, it will be automatically generated from the organization name
  • The organization will be created with isActive: true by default

What is returned: The complete organization object with all fields, including computed values like logoUrl and timestamps.

Note: This endpoint requires the Organizations.create permission. All validation errors will be returned with detailed field-level messages.

POST/organizations
Authorization
AuthorizationOAuth2 access token · headerrequired
Scopes:api:write
or
AuthorizationBearer token (JWT) · headerrequired
Query parameters
fieldsToReturnstring
Comma-separated list of top-level response fields to return. Overrides the endpoint compact default unless responseShape=full is used.
responseShapestring
Advanced override. Omit for the endpoint compact default. Use full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.
Allowed:compactfull
Header parameters
LT-Response-Shapestring
Advanced override. Set to full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.
Allowed:full
Request body
requiredapplication/json
addressCitystring
City
addressCountrystring
Country
addressHouseNumberstring
House number
addressStreetstring
Street address
addressZipstring
ZIP/Postal code
baseInvoiceInterestnumber
Base interest rate percentage (0-1000) used as the foundation for calculating default interest. Typically set by central banks (e.g., ECB, Bundesbank) and changes every six months. The final interest rate is baseInvoiceInterest + invoiceInterest.
colorstringrequired
Hex color code used to visually distinguish this organization in lists, projects, and throughout the application (required)
createProjectboolean
Create a default project for this organization (internal use only)
customFieldsobject
Custom field values as key-value pairs. Keys should match custom field IDs configured in workspace settings. Values must match the field type (string, number, boolean, date, etc.). Use the GET /administration/organization-settings/custom-fields endpoint to retrieve available custom fields and their configurations.
emailstring
Email address
enableInvoiceInterestboolean
Whether to charge interest on overdue invoices. Overrides workspace default. Set to true to enable, false to disable.
enableInvoiceReminderFeeboolean
Whether to charge a reminder fee for overdue invoices. Overrides workspace default. Set to true to enable, false to disable.
faxNumberstring
Fax number
hourRatenumber
Customer-specific hourly rate used for all billable time entries for this organization. Overrides workspace default. Used when creating invoices.
iconstring
Icon identifier for visual representation in lists and projects. Must be in the format `:icon_name:` (e.g., `:building:`, `:office:`, `:factory:`). Use standard emoji short names or custom icon names created in the workspace.
invoiceDueDaysnumber
Number of days after invoice date until payment is due. Valid range: 1-120. Overrides workspace default for this organization.
invoiceInterestnumber
Interest rate percentage (0-1000) added to baseInvoiceInterest to calculate the total default interest rate. According to BGB §288: typically +5% for private customers, +9% for businesses. Final rate = baseInvoiceInterest + invoiceInterest.
invoiceLanguagestring
Language code used for generating invoices and reminders for this organization (e.g., "en", "de", "fr"). Overrides workspace default.
invoiceReminderFeenumber
Amount charged as a reminder fee for overdue invoices. Valid range: 0-1000. Only applies if enableInvoiceReminderFee is true.
legalFormstring
Legal company form or structure (e.g., "GmbH", "AG", "LLC", "Inc.", "Ltd.")
logoIdstring
UUID of the uploaded logo file. To upload a logo: 1) Call POST /api/public/workspace/upload to upload the file, 2) Use the returned file ID here. The logo will appear in organization lists and project views.
namestringrequired
Full legal name of the organization (required)
parentOrganizationIdstring
UUID of the parent organization. Only top-level organizations (without a parent) can be selected as parents. Enables one-level hierarchical organization structure.
phoneNumberstring
Phone number
projectDocumentDefaultContactUserIdstring
UUID of the organization member (contact person) who will be automatically set as the recipient for new project documents (quotes, order confirmations, etc.) created for this organization.
projectDocumentEnableTocboolean
Whether to automatically include a table of contents in project documents (quotes, requirement documents, contracts) for this organization. Overrides workspace default.
projectDocumentHeadingStylestring
Formatting style for headings in project documents (e.g., "Sequential", "Normal"). Controls the hierarchy and appearance of document headings. Overrides workspace default.
projectDocumentTitlePageboolean
Whether to include a title/cover page in project documents for this organization. Overrides workspace default.
registrationCourtstring
Registration court
registrationNumberstring
Registration number
shortDescriptionstring
Short description of the organization
shortNamestring
Short abbreviation for the organization (3-5 characters, alphanumeric only). Used in projects and lists for quick identification. If not provided, will be auto-generated from the organization name.
max length 5
startOfCollaborationstring<date>
Date when the business relationship with this organization started. Format: ISO 8601 date (YYYY-MM-DD).
tagsstring[]
Array of tag UUIDs to categorize this organization. Tags enable cross-project organization and filtering. Use an empty array to remove all tags.
taxNumberstring
Tax identification number
typestringrequired
Type of organization defining the business relationship. Options: Customer (existing business partner), Prospect (potential customer), Supplier (external provider), Partner (strategic partner), ServiceProvider, Investor, Competitor, GovernmentAgency, EducationalInstitution, Target (target customer group).
Allowed:CustomerProspectTargetPartnerSupplierServiceProviderInvestorCompetitorGovernmentAgencyEducationalInstitution
websitestring
Website URL
Responses
200
addressCityobject
City
addressCountryobject
Country
addressHouseNumberobject
House number
addressStreetobject
Street address
addressZipobject
ZIP/Postal code
baseInvoiceInterestobject
Base invoice interest rate
colorstringrequired
Organization color (hex code)
createdAtstringrequired
Creation timestamp
customFieldsobject
Custom field values as key-value pairs. Keys match custom field IDs configured in workspace settings. Values match the field type (string, number, boolean, date, etc.). Use the GET /administration/organization-settings/custom-fields endpoint to retrieve available custom fields.
emailobject
Email address
enableInvoiceInterestobject
Enable invoice interest
enableInvoiceReminderFeeobject
Enable invoice reminder fee
faxNumberobject
Fax number
hourRateobject
Hourly rate
iconobject
Icon identifier
idstringrequired
Organization ID
invoiceDueDaysobject
Invoice due days
invoiceInterestobject
Invoice interest rate
invoiceLanguageobject
Invoice language code
invoiceReminderFeeobject
Invoice reminder fee amount
isActivebooleanrequired
Whether organization is active
legalFormobject
Legal form
logoUrlobject
Logo URL (publicly accessible)
namestringrequired
Organization name
parentOrganizationIdobject
Parent organization ID (for hierarchical organization structure)
parentOrganizationNameobject
Parent organization name
phoneNumberobject
Phone number
projectDocumentDefaultContactUserIdobject
Default contact user ID for project documents
projectDocumentEnableTocobject
Enable table of contents in project documents
projectDocumentHeadingStyleobject
Heading style for project documents
projectDocumentTitlePageobject
Show title page in project documents
registrationCourtobject
Registration court
registrationNumberobject
Registration number
shortDescriptionobject
Short description
shortNameobject
Short identifier
startOfCollaborationstring<date>
Start of collaboration date
tagsstring[]
Array of tag UUIDs assigned to this organization. Tags enable cross-project organization and filtering.
taxNumberobject
Tax identification number
typestringrequired
Organization type
Allowed:CustomerProspectTargetPartnerSupplierServiceProviderInvestorCompetitorGovernmentAgencyEducationalInstitution
updatedAtstringrequired
Last update timestamp
websiteobject
Website URL
400Validation errors
errorsobject
messagestring
statusCodenumber
401Unauthorized - Invalid or missing authentication token
403Forbidden - Insufficient API scopes or permissions
Request
curl -X POST "https://leadtime.app/api/public/organizations" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "addressCity": "New York",
  "addressCountry": "USA",
  "addressHouseNumber": "42A",
  "addressStreet": "123 Main St",
  "addressZip": "10001",
  "baseInvoiceInterest": 3,
  "color": "#FF5733",
  "createProject": false,
  "customFields": {
    "customField1": "value1",
    "customField2": 123
  },
  "email": "contact@acme.com",
  "enableInvoiceInterest": false,
  "enableInvoiceReminderFee": true,
  "faxNumber": "+1234567891",
  "hourRate": 150,
  "icon": ":building:",
  "invoiceDueDays": 30,
  "invoiceInterest": 5,
  "invoiceLanguage": "en",
  "invoiceReminderFee": 5,
  "legalForm": "GmbH",
  "logoId": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Acme Corporation",
  "parentOrganizationId": "123e4567-e89b-12d3-a456-426614174000",
  "phoneNumber": "+1234567890",
  "projectDocumentDefaultContactUserId": "123e4567-e89b-12d3-a456-426614174000",
  "projectDocumentEnableToc": true,
  "projectDocumentHeadingStyle": "classic",
  "projectDocumentTitlePage": true,
  "registrationCourt": "Munich District Court",
  "registrationNumber": "HRB 12345",
  "shortDescription": "Leading software development company",
  "shortName": "ACME",
  "startOfCollaboration": "2024-01-01",
  "tags": [
    "123e4567-e89b-12d3-a456-426614174000",
    "223e4567-e89b-12d3-a456-426614174001"
  ],
  "taxNumber": "DE123456789",
  "type": "Customer",
  "website": "https://acme.com"
}'
Response
{
  "addressCity": "New York",
  "addressCountry": "USA",
  "addressHouseNumber": "42A",
  "addressStreet": "123 Main St",
  "addressZip": "10001",
  "baseInvoiceInterest": 3,
  "color": "#FF5733",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "customFields": {
    "customField1": "value1",
    "customField2": 123
  },
  "email": "contact@acme.com",
  "enableInvoiceInterest": false,
  "enableInvoiceReminderFee": true,
  "faxNumber": "+1234567891",
  "hourRate": 150,
  "icon": "building",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "invoiceDueDays": 30,
  "invoiceInterest": 5,
  "invoiceLanguage": "en",
  "invoiceReminderFee": 5,
  "isActive": true,
  "legalForm": "GmbH",
  "logoUrl": "https://app.example.com/api/files/public/123e4567-e89b-12d3-a456-426614174000",
  "name": "Acme Corporation",
  "parentOrganizationId": "123e4567-e89b-12d3-a456-426614174000",
  "parentOrganizationName": "B. Braun",
  "phoneNumber": "+1234567890",
  "projectDocumentDefaultContactUserId": "123e4567-e89b-12d3-a456-426614174000",
  "projectDocumentEnableToc": true,
  "projectDocumentHeadingStyle": "classic",
  "projectDocumentTitlePage": true,
  "registrationCourt": "Munich District Court",
  "registrationNumber": "HRB 12345",
  "shortDescription": "Leading software development company",
  "shortName": "ACME",
  "startOfCollaboration": "2024-01-01",
  "tags": [
    "123e4567-e89b-12d3-a456-426614174000",
    "223e4567-e89b-12d3-a456-426614174001"
  ],
  "taxNumber": "DE123456789",
  "type": "Customer",
  "updatedAt": "2024-01-15T12:30:00.000Z",
  "website": "https://acme.com"
}