Create a project

Creates a new project and returns the created record.

Availability: Full version only — a Clock instance answers 404 for this endpoint.

Request

POST /api/v1/projects

curl --request POST \
     --url 'https://www.zep-online.de/zepinstanz/next/api/v1/projects' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer {token}' \
     --header 'Content-Type: application/json' \
     --data '{
       "name": "EU",
       "department_id": 1,
       "description": "Angebot|en:offer",
       "start_date": "2024-01-15",
       "end_date": "2024-01-16",
       "location_address": "string",
       "location_city": "string",
       "location_state": "string",
       "location_country": "string",
       "comments": "Wichtiger Kunde - mit Sorgfalt behandeln",
       "plan_expenses": 1.5,
       "plan_hours": 1.5,
       "plan_wage": 1.5,
       "plan_expenses_travel": 1.5,
       "cost_object": "string",
       "plan_hours_done": 1.5,
       "plan_hours_invoiced": 1.5,
       "customer_project_reference": "string",
       "customer_billing_address_id": 1,
       "customer_shipping_address_id": 1,
       "has_multiple_customers": true,
       "cost_object_identifier": 1,
       "project_status_id": "aktiv",
       "billing_type": 1,
       "default_billability": 1,
       "receipts_billability": 0,
       "currency": "EUR",
       "language": "de",
       "url": "https://www.zep-online.de/zepinstanz/next/api/v1/articles?page=1",
       "reference_commission": "string",
       "reference_procurement": "string",
       "reference_object": "string",
       "indicate_hours_for_daily_proof": 1,
       "indicate_remarks_for_daily_proof": 1,
       "indicate_all_locations_per_day": 1,
       "also_take_into_account_the_price_factors_for_hourly_rates": 1,
       "indicate_all_activities_per_day": 1,
       "employee_name_time_report_format": 1,
       "employee_name_project_sales_volume_format": 1,
       "employee_name_invoice_attachment_format": 1,
       "travel_flat_rate": 1.5,
       "reference_order": "string",
       "billing_tasks": true,
       "revenue_account": "8400",
       "plan_hours_children": 1.5,
       "plan_hours_per_day": 1.5,
       "plan_warning_percent": 1.5,
       "plan_warning_percent_2": 1.5,
       "plan_warning_percent_3": 1.5,
       "plan_can_exceed": 0,
       "keywords": [
         "string"
       ],
       "dynamicAttributes": [
         [
           "string"
         ]
       ],
       "categories": [
         "string"
       ],
       "customer_id": 1,
       "customer_contact_id": 789
     }'

Request body

Name
name
Type
string, required
Description
Name of the project. Must be unique within the tenant.
Name
department_id
Type
integer, required
Description
Identifier of the department the project is assigned to.
Name
description
Type
string, nullable
Description
Free-text description of the project.
Name
start_date
Type
string (date), required
Description
Date the project starts.
Name
end_date
Type
string (date), nullable
Description
Date the project ends, if it has a defined end.
Name
location_address
Type
string, nullable
Description
Street address of the project’s location.
Name
location_city
Type
string, nullable
Description
City of the project’s location.
Name
location_state
Type
string, nullable
Description
State or region of the project’s location.
Name
location_country
Type
string, nullable
Description
Country of the project’s location.
Name
comments
Type
string, nullable
Description
Free-text internal comments about the project.
Name
plan_expenses
Type
number, nullable
Description
Planned total expenses budgeted for the project.
Name
plan_hours
Type
number, nullable
Description
Planned total hours budgeted for the project.
Name
plan_wage
Type
number, nullable
Description
Planned total wage cost budgeted for the project.
Name
plan_expenses_travel
Type
number, nullable
Description
Planned travel expenses budgeted for the project.
Name
cost_object
Type
string, nullable
Description
Cost object the project’s bookings are assigned to.
Name
plan_hours_done
Type
number, nullable
Description
Hours already recorded against the project.
Name
plan_hours_invoiced
Type
number, nullable
Description
Hours already invoiced for the project.
Name
customer_project_reference
Type
string, nullable
Description
Customer’s own reference number for this project.
Name
customer_billing_address_id
Type
integer, nullable
Description
Identifier of the customer address used for billing.
Name
customer_shipping_address_id
Type
integer, nullable
Description
Identifier of the customer address used for shipping.
Name
has_multiple_customers
Type
boolean, nullable
Description
Whether the project can be billed to more than one customer.
Name
cost_object_identifier
Type
integer, nullable
Description
External identifier of the cost object, used for accounting export.
Name
project_status_id
Type
string, nullable
Description
Identifier of the project’s current status.
Name
billing_type
Type
integer, nullable
Description
How the project is billed: hourly rate, daily rate or flat rate.
One of: 1, 2, 3
Name
default_billability
Type
integer, nullable
Description
Default billability applied to new time entries on this project.
One of: 1, 2, 3, 4
Name
receipts_billability
Type
integer, nullable
Description
Default billability applied to new receipts on this project.
One of: 0, 1, 2, 3
Name
currency
Type
string, nullable
Description
Currency used for monetary values in this project.
Name
language
Type
string, nullable
Description
Language used for documents generated for this project.
One of: "de", "de_at", "de_ch", "en", "en_de", "en_eu", "en_gb", "en_us", "es", "fr", "fr_ch", "fr_de", "pl", "sk", "tr"
Name
url
Type
string, nullable
Description
URL associated with the project, for example a customer portal link.
Name
reference_commission
Type
string, nullable
Description
Customer’s commission reference for this project.
Name
reference_procurement
Type
string, nullable
Description
Customer’s procurement reference for this project.
Name
reference_object
Type
string, nullable
Description
Customer’s object reference for this project.
Name
indicate_hours_for_daily_proof
Type
integer, nullable
Description
Whether to show the hours field on the daily proof of work document.
Name
indicate_remarks_for_daily_proof
Type
integer, nullable
Description
Whether to show the remarks field on the daily proof of work document.
Name
indicate_all_locations_per_day
Type
integer, nullable
Description
Whether to list all locations per day on the daily proof of work document.
Name
also_take_into_account_the_price_factors_for_hourly_rates
Type
integer, nullable
Description
Whether hourly rates also take the project’s price factors into account.
Name
indicate_all_activities_per_day
Type
integer, nullable
Description
Whether to list all activities per day on the daily proof of work document.
Name
employee_name_time_report_format
Type
integer, nullable
Description
Format used to display the employee’s name on the time report.
Name
employee_name_project_sales_volume_format
Type
integer, nullable
Description
Format used to display the employee’s name on the project sales volume report.
Name
employee_name_invoice_attachment_format
Type
integer, nullable
Description
Format used to display the employee’s name on the invoice attachment.
Name
travel_flat_rate
Type
number, nullable
Description
Flat rate charged for travel on this project.
Name
reference_order
Type
string, nullable
Description
Customer’s order reference for this project.
Name
billing_tasks
Type
boolean, nullable
Description
Whether the project’s tasks can each carry their own billing type.
Name
revenue_account
Type
string, nullable
Description
Revenue account the project’s turnover is booked to.
Name
plan_hours_children
Type
number, nullable
Description
Planned hours budgeted across the project’s tasks.
Name
plan_hours_per_day
Type
number, nullable
Description
Planned hours budgeted per day for the project.
Name
plan_warning_percent
Type
number, nullable
Description
Percentage of the planned budget at which a warning is raised.
Name
plan_warning_percent_2
Type
number, nullable
Description
Second warning threshold, as a percentage of the planned budget.
Name
plan_warning_percent_3
Type
number, nullable
Description
Third warning threshold, as a percentage of the planned budget.
Name
plan_can_exceed
Type
integer, nullable
Description
Whether recorded hours may exceed the planned budget.
One of: 0, 1, 2, 3, 4
Name
keywords
Type
array of string, nullable
Description
Free-text keywords used to search for the project.
Name
dynamicAttributes
Type
array of array, nullable
Description
Dynamic attributes to configure for the project.
Name
categories
Type
array of string, nullable
Description
Categories to assign to the project.
Name
customer_id
Type
integer, nullable
Description
Identifier of the customer this project belongs to.
Name
customer_contact_id
Type
integer, nullable
Description
Identifier of the customer contact responsible for this project.

Response

{
  "data": {
    "id": 1,
    "name": "EU",
    "description": "Angebot|en:offer",
    "start_date": "2024-01-15T00:00:00.000000Z",
    "end_date": "2024-01-16T00:00:00.000000Z",
    "project_status_id": "aktiv",
    "status": {
      "id": 1,
      "name": "EU",
      "description": "Angebot|en:offer",
      "bookable": true,
      "order": 0,
      "color": "#664599",
      "abrechnungsrelevant": "string"
    },
    "comments": "Wichtiger Kunde - mit Sorgfalt behandeln",
    "cost_object": "string",
    "cost_object_identifier": "string",
    "created": "2024-07-20T11:30:00.000000Z",
    "modified": "2024-07-20T12:30:00.000000Z",
    "keywords": [
      null
    ],
    "reference_order": "string",
    "reference_commission": "string",
    "reference_procurement": "string",
    "reference_object": "string",
    "language": "de",
    "currency": "EUR",
    "url": "https://www.zep-online.de/zepinstanz/next/api/v1/articles?page=1",
    "location_address": "string",
    "location_city": "string",
    "location_state": "string",
    "location_country": "string",
    "revenue_account": "8400",
    "customer_id": "string",
    "customer_contact_id": "string",
    "customer_project_reference": "string",
    "customer_billing_address_id": "string",
    "customer_shipping_address_id": "string",
    "has_multiple_customers": true,
    "department_id": 1,
    "billing_type": {
      "id": 1,
      "name": "Stundensatz"
    },
    "billing_tasks": "string",
    "plan_hours": 1.5,
    "plan_hours_children": 1.5,
    "plan_hours_per_day": 1.5,
    "plan_can_exceed": {
      "id": 1,
      "name": "Yes, all times can exceed the plan hours"
    },
    "plan_warning_percent": 1.5,
    "plan_warning_percent_2": 1.5,
    "plan_warning_percent_3": 1.5,
    "plan_wage": 1.5,
    "plan_expenses": 1.5,
    "plan_expenses_travel": 1.5,
    "plan_hours_done": 1.5,
    "plan_hours_invoiced": 1.5,
    "default_billability": {
      "id": 1,
      "name": "Fakturierbar, durch den Mitarbeiter änderbar"
    },
    "receipts_billability": {
      "id": 1,
      "name": "Specify billable amount apart"
    },
    "plan_wage_children": 0,
    "categories": [
      {
        "name": "EU",
        "description": {
          "de": "string",
          "en": "string",
          "fr": "string",
          "es": "string",
          "pl": "string"
        },
        "type": {
          "id": "string",
          "name": "Mitarbeiter/in"
        }
      }
    ],
    "dynamicAttributes": [
      {
        "name": "EU",
        "value": "Max Mustermann (Bruder)",
        "type": "Text",
        "description": {
          "de": "string",
          "en": "string",
          "fr": "string",
          "es": "string",
          "pl": "string"
        }
      }
    ],
    "categories_count": 0,
    "dynamicAttributes_count": 0,
    "tasks_count": 0,
    "employees_count": 0,
    "activities_count": 0,
    "priceTables": [
      {
        "id": 1,
        "start_date": "2024-01-15T00:00:00.000000Z",
        "customer_number": "K-12345",
        "project_id": 16,
        "type": {
          "id": "string",
          "name": "Basispreistabelle"
        },
        "prices": [
          {
            "id": 1,
            "price_group": "Junior-Entwickler",
            "price": 1.5,
            "price_table_id": "string",
            "type": {
              "id": "string",
              "name": "Stundensatz"
            },
            "activity": "string",
            "ahr_factor": 1.5
          }
        ],
        "factors": [
          {
            "id": 1,
            "day": {
              "id": 1,
              "name": "So"
            },
            "start_time": "11:10:49",
            "end_time": "15:10:49",
            "factor": 1.5,
            "price_table_id": 1,
            "activity_id": 1
          }
        ]
      }
    ],
    "end_customer_number": "string"
  }
}

Response fields

Name
id
Type
integer
Description
Unique identifier of the project.
Name
name
Type
string, nullable
Description
Name of the project.
Name
description
Type
string, nullable
Description
Free-text description of the project.
Name
start_date
Type
string (date-time), nullable
Description
Date the project starts.
Name
end_date
Type
string (date-time), nullable
Description
Date the project ends, if it has a defined end.
Name
project_status_id
Type
string
Description
Identifier of the project’s current status.
Name
status
Type
object (ProjectStatus)
Description
The project’s current status, including its label and whether it is billable.
Name
status.id
Type
integer
Description
Identifier of the status. The short name doubles as the primary key.
Name
status.name
Type
string
Description
Short name of the status, as shown in the project list.
Name
status.description
Type
string, nullable
Description
Longer label describing what the status means.
Name
status.bookable
Type
boolean
Description
Whether time can still be booked on a project carrying this status.
Name
status.order
Type
integer
Description
Sort position of the status in selection lists.
Name
status.color
Type
string, nullable
Description
Colour the status is rendered in, as a hex value.
Name
status.abrechnungsrelevant
Type
string
Description
Whether projects with this status are included in billing runs.
Name
comments
Type
string, nullable
Description
Free-text internal comments about the project.
Name
cost_object
Type
string, nullable
Description
Cost center the project’s bookings are assigned to, for accounting purposes.
Name
cost_object_identifier
Type
string, nullable
Description
Cost carrier assigned to the project, a separate accounting dimension from the cost center, used for accounting export.
Name
created
Type
string (date-time), nullable
Description
Date and time the project was created.
Name
modified
Type
string (date-time), nullable
Description
Date and time the project was last modified.
Name
keywords
Type
array of object
Description
Free-text keywords used to search for the project.
Name
reference_order
Type
string, nullable
Description
Customer’s order reference for this project.
Name
reference_commission
Type
string, nullable
Description
Customer’s commission reference for this project.
Name
reference_procurement
Type
string, nullable
Description
Customer’s procurement reference for this project.
Name
reference_object
Type
string, nullable
Description
Customer’s object reference for this project.
Name
language
Type
string, nullable
Description
Language used for documents generated for this project.
Name
currency
Type
string, nullable
Description
Currency used for monetary values in this project.
Name
url
Type
string, nullable
Description
URL associated with the project, for example a customer portal link.
Name
location_address
Type
string, nullable
Description
Street address of the project’s location.
Name
location_city
Type
string, nullable
Description
City of the project’s location.
Name
location_state
Type
string, nullable
Description
State or region of the project’s location.
Name
location_country
Type
string, nullable
Description
Country of the project’s location.
Name
revenue_account
Type
string, nullable
Description
Revenue account the project’s turnover is booked to.
Name
customer_id
Type
string, nullable
Description
Identifier of the customer this project belongs to.
Name
customer_contact_id
Type
string, nullable
Description
Identifier of the customer contact responsible for this project.
Name
customer_project_reference
Type
string, nullable
Description
Customer’s own reference number for this project.
Name
customer_billing_address_id
Type
string, nullable
Description
Identifier of the customer address used for billing.
Name
customer_shipping_address_id
Type
string, nullable
Description
Identifier of the customer address used for shipping.
Name
has_multiple_customers
Type
boolean, nullable
Description
Whether the project can be billed to more than one customer.
Name
department_id
Type
integer, nullable
Description
Identifier of the department the project is assigned to.
Name
billing_type
Type
object, nullable
Description
How the project is billed: hourly rate, daily rate or flat rate.
Name
billing_type.id
Type
integer
Description
The stored value. Compare against this, not against name.
Name
billing_type.name
Type
string
Description
The human-readable label, delivered in the tenant’s language. Do not parse it.
One of: "Stundensatz", "Tagessatz", "Pausch"
Name
billing_tasks
Type
string, nullable
Description
Whether the project’s tasks can each carry their own billing type.
Name
plan_hours
Type
number, nullable
Description
Planned total hours budgeted for the project.
Name
plan_hours_children
Type
number, nullable
Description
Planned hours budgeted across the project’s tasks.
Name
plan_hours_per_day
Type
number, nullable
Description
Planned hours budgeted per day for the project.
Name
plan_can_exceed
Type
object, nullable
Description
Whether recorded hours may exceed the planned budget: for all times, only for non-billable times, not at all, only for travel or non-billable times, or only for travel times.
Name
plan_can_exceed.id
Type
integer
Description
The stored value. Compare against this, not against name.
Name
plan_can_exceed.name
Type
string
Description
The human-readable label, delivered in the tenant’s language. Do not parse it.
One of: "Yes, all times can exceed the plan hours", "Yes, but only non-billable times can exceed the plan hours", "No, all times can not exceed the plan hours", "Yes, but only travel or non-billable times can exceed the plan hours", "Yes, but only travel times can exceed the plan hours"
Name
plan_warning_percent
Type
number, nullable
Description
Percentage of the planned budget at which a warning is raised.
Name
plan_warning_percent_2
Type
number, nullable
Description
Second warning threshold, as a percentage of the planned budget.
Name
plan_warning_percent_3
Type
number, nullable
Description
Third warning threshold, as a percentage of the planned budget.
Name
plan_wage
Type
number, nullable
Description
Planned total wage cost budgeted for the project.
Name
plan_expenses
Type
number, nullable
Description
Planned total expenses budgeted for the project.
Name
plan_expenses_travel
Type
number, nullable
Description
Planned travel expenses budgeted for the project.
Name
plan_hours_done
Type
number, nullable
Description
Hours already recorded against the project.
Name
plan_hours_invoiced
Type
number, nullable
Description
Hours already invoiced for the project.
Name
default_billability
Type
object
Description
Default billability applied to new time entries on this project.
Name
default_billability.id
Type
integer
Description
The stored value. Compare against this, not against name.
Name
default_billability.name
Type
string
Description
The human-readable label, delivered in the tenant’s language. Do not parse it.
One of: "Fakturierbar, durch den Mitarbeiter änderbar", "Fakturierbar, durch den Mitarbeiter nicht änderbar", "Not billable, user can change the flag", "Not billable, user can not change the flag"
Name
receipts_billability
Type
object, nullable
Description
Default billability applied to new receipts on this project.
Name
receipts_billability.id
Type
integer
Description
The stored value. Compare against this, not against name.
Name
receipts_billability.name
Type
string
Description
The human-readable label, delivered in the tenant’s language. Do not parse it.
One of: "Specify billable amount apart", "Vorbelegung identisch weiterfakturieren", "Vorbelegung nicht weiterfakturieren", "keine Belegerfassung möglich"
Name
plan_wage_children
Type
number, nullable
Description
Planned wage cost budgeted across the project’s tasks.
Name
categories
Type
array of Category
Description
Categories assigned to the project.
Name
categories.name
Type
string
Description
Name of the category, shown wherever an entity is tagged with it.
Name
categories.description
Type
object
Description
Longer explanation of what this category should be used for.
Name
categories.type
Type
object
Description
The kind of entity this category can be attached to, e.g. employee, project or customer.
Name
dynamicAttributes
Type
array of DynamicAttribute
Description
Dynamic attributes configured for the project.
Name
dynamicAttributes.name
Type
string
Description
Name of the dynamic attribute definition this value was entered for.
Name
dynamicAttributes.value
Type
any
Description
The stored value; its shape depends on the neighbouring type field (a string, a number, a boolean, a date, an employee reference, or a list of option values).
Name
dynamicAttributes.type
Type
string
Description
The data type of this attribute, e.g. text, number, date or options, which decides how to interpret value.
One of: "Text", "Integer", "Float", "URL", "E-Mail", "Datum", "Uhrzeit", "Datetime", "Boolean", "Betrag", "Optionen", "Prozent", "Time period", "Textarea", "Users", "Upload"
Name
dynamicAttributes.description
Type
object, nullable
Description
Explanation of what this attribute captures, as configured on its definition.
Name
categories_count
Type
integer
Description
Number of categories assigned to the project.
Name
dynamicAttributes_count
Type
integer
Description
Number of dynamic attributes configured for the project.
Name
tasks_count
Type
integer
Description
Number of tasks belonging to the project.
Name
employees_count
Type
integer
Description
Number of employees assigned to the project.
Name
activities_count
Type
integer
Description
Number of activities assigned to the project.
Name
priceTables
Type
array of PriceTable
Description
Price tables assigned to the project. Only appears when appended to the response.
Name
priceTables.id
Type
integer
Description
Unique identifier of the price table.
Name
priceTables.start_date
Type
string (date-time), nullable
Description
Date from which the price table applies.
Name
priceTables.customer_number
Type
string, nullable
Description
Number of the customer this price table belongs to, for a customer-level price table.
Name
priceTables.project_id
Type
integer, nullable
Description
Identifier of the project this price table belongs to, for a project-level price table.
Name
priceTables.type
Type
object, nullable
Description
Whether the price table is scoped to a customer or a project.
Name
priceTables.prices
Type
array of Price
Description
Prices defined in this price table.
Name
priceTables.factors
Type
array of PriceFactor
Description
Time-based factors defined in this price table, e.g. for night or weekend surcharges.
Name
end_customer_number
Type
string, nullable
Description
The number the end customer is filed under in the customer’s own system. Only on instances with the MOD_PCS extension. Not a generally available feature.

Generated from the OpenAPI specification — edit the source code, not this page.

GET Get a project PATCH Update a project