Custom Fields

Custom fields let you store account-specific data on reference projects: budgets, durations, hours, quantities, or a value picked from a fixed list. This guide shows how to read and write custom field values through the reference project endpoints.

Overview

Custom fields are configured once for your whole account. Each definition has a permanent field_name, a type, and a set of translated labels. Every reference project in the account then carries the same set of fields, and you set the values per project.

You manage values through the reference project endpoints:

• Include a custom_fields array when you create or update a project.
• Add include_custom_fields=true when you read a project to get its values back.

Custom fields must be enabled for your account by your account representative or Flowcase support. Requests need write permission on the reference project. See Reference Projects for the full project schema and the role each operation requires, and Managing References for the wider customer and project sync workflow.

Multilingual fields use legacy language codes by default (int for English, no for Norwegian). Pass use_legacy_codes=false on the create and update endpoints to use ISO 639-1 codes instead. See Country & Language Codes for the full list.

Custom field definitions

Before you set values, you need to know the definitions available in your account. You can see them on the Custom Fields settings page in Flowcase. A definition looks like this:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "company_id": "company-uuid",
    "field_name": "project_budget",
    "field_type": "currency_amount",
    "field_label": { "int": "Project Budget", "no": "Prosjektbudsjett" },
    "field_tooltip": { "int": "Total project budget" },
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "field_name": "project_status",
    "field_type": "single_select",
    "field_label": { "int": "Project Status" },
    "options": [
      {
        "id": "opt-uuid-1",
        "external_unique_id": "in_progress",
        "name": { "int": "In Progress", "no": "Pågår" }
      },
      {
        "id": "opt-uuid-2",
        "external_unique_id": "completed",
        "name": { "int": "Completed", "no": "Fullført" }
      }
    ]
  }
]

Two things matter when you write values:

• field_name identifies the field. You pass it as name in every request.
• For single select fields, note the external_unique_id of each option. You need it to set a value.

Create a project with custom fields

POST https://<subdomain>.flowcase.com/api/v2/company/cv/customers/<customer_id>/projects

{
  "company_project": {
    "project_name": {
      "int": "New Office Building",
      "no": "Nytt kontorbygg"
    },
    "custom_fields": [
      {
        "name": "project_budget",
        "amount": 5000000,
        "currency": "nok"
      },
      {
        "name": "project_duration",
        "from": "2023-01",
        "to": "2024-06"
      },
      {
        "name": "team_size",
        "value": "25"
      },
      {
        "name": "project_status",
        "value": "completed"
      },
      {
        "name": "effort_hours",
        "amount": "1500",
        "unit": "hours"
      }
    ]
  }
}

An unknown name returns 404, so the whole request fails. Check the definitions first.

Update a project's custom fields

PUT https://<subdomain>.flowcase.com/api/v2/company/cv/customers/<customer_id>/projects/<project_id>

The body uses the same structure as create. Include only the custom fields you want to create or update. Custom fields you leave out keep their current values.

{
  "company_project": {
    "custom_fields": [
      {
        "name": "project_budget",
        "amount": 9000000,
        "currency": "eur"
      }
    ]
  }
}

Permitted parameters

These parameters are permitted for each entry in the custom_fields array:

Parameter	Used by
name	All types (required): the field_name from the definition
value	numeric, single_select
amount	currency_amount, quantity
currency	currency_amount
from	year_month_range
to	year_month_range
unit	quantity
sensitivity	All types (anonymized or confidential)
anonymized	All types (multilingual object)

value_id is not permitted through these endpoints. For single select fields, use value with the option's external_unique_id.

Single select fields

The value parameter must be the external_unique_id of the option, not:

• the option's UUID (id)
• the option's display name

Correct:

{
  "name": "project_status",
  "value": "completed"
}

Here "completed" is the external_unique_id from the definition's options.

Incorrect (returns 422):

{
  "name": "project_status",
  "value": "Completed"
}

{
  "name": "project_status",
  "value_id": "opt-uuid-2"
}

Clearing a single select value

Pass null as the value to unset the field:

{
  "name": "project_status",
  "value": null
}

The response returns 200 with the field's value set to null. Passing value_id: null does not clear the field, it returns 422.

Read custom field values

Custom fields are left out of project responses unless you ask for them:

GET https://<subdomain>.flowcase.com/api/v2/company/cv/customers/<customer_id>/projects/<project_id>?include_custom_fields=true

Or when listing a customer's projects. company_customer_id is required here; without it the request returns 404:

GET https://<subdomain>.flowcase.com/api/v2/company/cv/projects?company_customer_id=<customer_id>&include_custom_fields=true

Only the exact string true turns this on. Any other value omits the array.

{
  "id": "project-uuid",
  "project_name": { "int": "Office Building" },
  "custom_fields": [
    {
      "name": "project_budget",
      "type": "currency_amount",
      "amount": 5000000,
      "currency": "nok",
      "sensitivity": null,
      "anonymized": {}
    },
    {
      "name": "project_status",
      "type": "single_select",
      "value": {
        "id": "opt-uuid-2",
        "external_unique_id": "completed",
        "name": { "int": "Completed", "no": "Fullført" }
      },
      "sensitivity": null,
      "anonymized": {}
    }
  ]
}

The array holds every custom field defined for your account, so fields you have not set appear with null values. Single select values come back as an object with the option's id, external_unique_id, and translated name.

Field types

Numeric

Stores integer or decimal values. Values are returned as decimal strings, so "42" comes back as "42.0".

{
  "name": "team_size",
  "value": "42",
  "sensitivity": "anonymized",
  "anonymized": {
    "int": "~40",
    "no": "~40"
  }
}

Year month range

Stores date ranges with year and month precision. Use YYYY-MM format.

{
  "name": "project_duration",
  "from": "2023-01",
  "to": "2024-06"
}

Currency amount

Stores monetary values with a currency code.

{
  "name": "project_budget",
  "amount": 1500000,
  "currency": "nok"
}

Validations:

• amount must be a non-negative integer.
• currency must be a valid lowercase currency code. Uppercase codes such as "NOK" return 422.

Single select

Selects one of the options on the definition. Pass the option's external_unique_id.

{
  "name": "project_status",
  "value": "completed"
}

Quantity

Stores numeric amounts with units. unit is optional and must be one of the supported unit codes, so an unrecognised code returns 422. Amounts are returned as decimal strings.

{
  "name": "effort_hours",
  "amount": "150",
  "unit": "hours"
}

Error handling

Status	Cause
401	User not authenticated
403	User lacks write permission on the reference project
404	Reference project not found, or custom field definition not found
422	Validation error

See Errors & Response Codes for the full list of status codes the API returns.

Common causes of 422

• Single select: using the display name instead of the external_unique_id.
• Single select: using value_id, which these endpoints do not permit.
• Single select: no option matches the value you sent.
• Currency amount: invalid currency code, or a negative amount.
• Quantity: unrecognised unit code.
• Missing field: required parameters not provided.

Frequently asked questions

How do I give feedback to the Flowcase team?

Contact your Customer Success Manager or your technical contact at Flowcase.

Can I change the name of a custom field?

No. The name is permanent and cannot be changed after the field is created. It is the key you use to read and update the field, so changing it in production would break any integration that touches that field.

You can change the translated labels for custom fields on the Custom Fields settings page in Flowcase.

How do I add a new custom field?

New custom fields can only be configured by Flowcase. Your Customer Success Manager can add fields for you.

Can I use different custom fields on different reference projects?

No. Custom fields are configured for the whole account and are included in every reference project in it. The configuration cannot be varied per project.