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:

First, call POST /api/public/workspace/upload to upload the logo file
The upload endpoint returns a file ID (UUID)
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

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

400

Validation errors

errorsobject

messagestring

statusCodenumber

401

Unauthorized - Invalid or missing authentication token

403

Forbidden - Insufficient API scopes or permissions

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

OAuth2 access tokenRemember on this deviceInclude my values in samples

Parameters

fieldsToReturnqueryComma-separated list of top-level response fields to return. Overrides the endpoint compact default unless responseShape=full is used.responseShapequeryAdvanced 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.LT-Response-ShapeheaderAdvanced override. Set to full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.

Bodyapplication/json

Request body

{
  "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"
}

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"
}'

const response = await fetch("https://leadtime.app/api/public/organizations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"addressCity\": \"New York\",\n  \"addressCountry\": \"USA\",\n  \"addressHouseNumber\": \"42A\",\n  \"addressStreet\": \"123 Main St\",\n  \"addressZip\": \"10001\",\n  \"baseInvoiceInterest\": 3,\n  \"color\": \"#FF5733\",\n  \"createProject\": false,\n  \"customFields\": {\n    \"customField1\": \"value1\",\n    \"customField2\": 123\n  },\n  \"email\": \"contact@acme.com\",\n  \"enableInvoiceInterest\": false,\n  \"enableInvoiceReminderFee\": true,\n  \"faxNumber\": \"+1234567891\",\n  \"hourRate\": 150,\n  \"icon\": \":building:\",\n  \"invoiceDueDays\": 30,\n  \"invoiceInterest\": 5,\n  \"invoiceLanguage\": \"en\",\n  \"invoiceReminderFee\": 5,\n  \"legalForm\": \"GmbH\",\n  \"logoId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"name\": \"Acme Corporation\",\n  \"parentOrganizationId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"phoneNumber\": \"+1234567890\",\n  \"projectDocumentDefaultContactUserId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"projectDocumentEnableToc\": true,\n  \"projectDocumentHeadingStyle\": \"classic\",\n  \"projectDocumentTitlePage\": true,\n  \"registrationCourt\": \"Munich District Court\",\n  \"registrationNumber\": \"HRB 12345\",\n  \"shortDescription\": \"Leading software development company\",\n  \"shortName\": \"ACME\",\n  \"startOfCollaboration\": \"2024-01-01\",\n  \"tags\": [\n    \"123e4567-e89b-12d3-a456-426614174000\",\n    \"223e4567-e89b-12d3-a456-426614174001\"\n  ],\n  \"taxNumber\": \"DE123456789\",\n  \"type\": \"Customer\",\n  \"website\": \"https://acme.com\"\n}"
});

import requests

response = requests.post(
    "https://leadtime.app/api/public/organizations",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"addressCity\": \"New York\",\n  \"addressCountry\": \"USA\",\n  \"addressHouseNumber\": \"42A\",\n  \"addressStreet\": \"123 Main St\",\n  \"addressZip\": \"10001\",\n  \"baseInvoiceInterest\": 3,\n  \"color\": \"#FF5733\",\n  \"createProject\": false,\n  \"customFields\": {\n    \"customField1\": \"value1\",\n    \"customField2\": 123\n  },\n  \"email\": \"contact@acme.com\",\n  \"enableInvoiceInterest\": false,\n  \"enableInvoiceReminderFee\": true,\n  \"faxNumber\": \"+1234567891\",\n  \"hourRate\": 150,\n  \"icon\": \":building:\",\n  \"invoiceDueDays\": 30,\n  \"invoiceInterest\": 5,\n  \"invoiceLanguage\": \"en\",\n  \"invoiceReminderFee\": 5,\n  \"legalForm\": \"GmbH\",\n  \"logoId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"name\": \"Acme Corporation\",\n  \"parentOrganizationId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"phoneNumber\": \"+1234567890\",\n  \"projectDocumentDefaultContactUserId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"projectDocumentEnableToc\": true,\n  \"projectDocumentHeadingStyle\": \"classic\",\n  \"projectDocumentTitlePage\": true,\n  \"registrationCourt\": \"Munich District Court\",\n  \"registrationNumber\": \"HRB 12345\",\n  \"shortDescription\": \"Leading software development company\",\n  \"shortName\": \"ACME\",\n  \"startOfCollaboration\": \"2024-01-01\",\n  \"tags\": [\n    \"123e4567-e89b-12d3-a456-426614174000\",\n    \"223e4567-e89b-12d3-a456-426614174001\"\n  ],\n  \"taxNumber\": \"DE123456789\",\n  \"type\": \"Customer\",\n  \"website\": \"https://acme.com\"\n}",
)

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"
}

{
  "errors": {
    "color": [
      "Color must be a valid hex code"
    ],
    "name": [
      "Name is required"
    ],
    "type": [
      "Type is required"
    ]
  },
  "message": "Bad Request",
  "statusCode": 400
}