Skip to main content

Using custom fields in the Connection API

Project leaders can add custom fields to issues in BIMcollab, for example, to record a discipline, a cost code or a building zone. This article explains how your application can read and write these fields with the Connection API.

💡 Tip: Visit our article Set up custom fields for Issue management to learn more

Before you begin

  • Custom fields are only available in the Connection API (version bc_2.1). The generic BCF-API (version 2.1) doesn't support them.

  • You need an access token. See How to authenticate with the BIMcollab API.

  • You need the project ID. See Getting started with the Connection API.

  • You need a tool to send requests. Each step below shows two options:

    • Option A: Postman: the collection you created during authorization adds the access token to every request.

    • Option B: cURL: replace <access-token> with your access token.

How custom fields work in the API

Custom fields are stored in two places:

  • The project extensions describe the fields: their number (index), name (label), whether they are required, and, for some fields, the list of allowed values.

  • Each issue stores the values of its custom fields, identified by the index.

The index connects the two. For example, index 11 in an issue refers to the field with index 11 in the extensions.

Project extensions                       Issue (topic)
"index": 11, "label": "Custom 1"    ←→   "customfields": { "11": "1" }

Retrieve and update Issue custom fields

Follow the steps below to extract and update your Issues custom fields.

Step 1: Get the field definitions

Option A: Postman

  1. Create a new GET request in your collection.

  2. Paste the endpoint below in the URL field. Replace the placeholder with your project ID:

https://playground.bimcollab.com/bcf/bc_2.1/projects/<project-id>/extensions

  1. Click Send.

Option B: cURL

curl -X GET "https://playground.bimcollab.com/bcf/bc_2.1/projects/<project-id>/extensions" \
  -H "Authorization: Bearer <access-token>"

The fields list in the response describes each custom field:

"fields": [
  {
    "index": 11,
    "field": "custom1",
    "label": "Custom 1",
    "mandatory": false,
    "values": [
      { "internal_id": 0, "value": null, "label": "Not set", "is_active": true },
      { "internal_id": 1, "value": "1", "is_active": true },
      { "internal_id": 2, "value": "2", "is_active": true },
      { "internal_id": 3, "value": "3", "is_active": true }
    ]
  }
]

Property

Meaning

index

The number that identifies the field in issues.

field

The internal name of the field.

label

The name of the field as users see it in BIMcollab.

mandatory

true if the project leader made the field required.

values

The allowed values. Only fields with a fixed list of values have this property.

Inside values:

  • value: the value you send and receive in issues.

  • label: the text users see, when it is different from the value.

  • is_active: false if the value can no longer be selected.

Step 2: Read custom field values

Get an issue.

Option A: Postman

  1. Create a new GET request in your collection.

  2. Paste the endpoint below in the URL field. Replace the placeholders with your <project-id> and <topic-guid>:

https://playground.bimcollab.com/bcf/bc_2.1/projects/<project-id>/topics/<topic-guid>

  1. Click Send.

Option B: cURL

curl -X GET "https://playground.bimcollab.com/bcf/bc_2.1/projects/<project-id>/topics/<topic-guid>" \
  -H "Authorization: Bearer <access-token>"

The customfields object in the response contains the values. Each key is a field index, and each value is the current value of that field:

"customfields": {
  "11": "1",
  "12": "A",
  "13": "two",
  "14": "three"
}

To show the field names, match each index with the label from the extensions.

Step 3: Write custom field values

Example of creating an issue with custom fields. The request body below contains the issue and its custom field values:

{
  "title": "Intersections check: beam inside wall",
  "customfields": {
    "11": "1",
    "12": "A",
    "13": "two",
    "14": "three"
  }
}

Option A: Postman

  1. Create a new POST request in your collection.

  2. Paste the endpoint below in the URL field. Replace the placeholder with your <project-id>:

https://playground.bimcollab.com/bcf/bc_2.1/projects/<project-id>/topics

  1. Go to the Body tab and select raw and JSON.

  2. Paste the request body.

  3. Click Send.

Option B: cURL

curl -X POST "https://playground.bimcollab.com/bcf/bc_2.1/projects/<project-id>/topics" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Intersections check: beam inside wall",
    "customfields": {
      "11": "1",
      "12": "A",
      "13": "two",
      "14": "three"
    }
  }'

Keep these rules in mind:

Troubleshooting

Problem

Possible cause

Solution

The response has no customfields.

You used version 2.1, or you requested the list of issues.

Use bc_2.1, and get one issue at a time.

A custom field value disappeared after an update.

The PUT request didn't include all custom fields.

Get the issue first and send it back complete.

400 Bad request when you create an issue.

A mandatory field is empty, or a value isn't in the list of allowed values.

Check mandatory and values in the extensions.

Related articles

Related Articles
Did this answer your question?