Skip to main content

How to manage custom fields and values via the OpenAPI

  • Updated

The Weel OpenAPI lets you create custom fields and keep their values in sync with your source system — with no cap on the number of values. Define a structure like project code or cost centre once, then keep thousands of options current automatically instead of re-entering them by hand.

Before you start

You will need:

  • A Weel Enterprise plan.
  • Admin access, or the API permission enabled for your role.
  • An API key — see How to generate and manage API keys How to generate and manage API keys.
  • Your Client ID, shown on the Settings > API page in the Weel web app.

Include your API key as a bearer token in the Authorization header of every request. The full endpoint reference is at developer.letsweel.com.

Steps

1. Create a custom field

Send POST /v1/businesses/{client_id}/custom-fields with:

  • name — the display name (for example, "Project Code"). Must be unique within your business.
  • field_type — LIST for a field with a set of selectable options, or FREE_TEXT for open entry.
  • budget_setting (optional) — which budgets the field is assigned to: ALL_CURRENT_AND_NEW (the default), SOME, or NONE.

Update a field later with PATCH /v1/businesses/{client_id}/custom-fields/{custom_field_id}, or delete it with DELETE — deleting a field also removes all of its options and budget links.

2. Sync the field's values

For LIST fields, manage the selectable options:

  1. Add options with POST /v1/businesses/{client_id}/custom-fields/{custom_field_id}/options. There's no cap on the number of options.
  2. Rename an option with PATCH .../options/{option_id}.
  3. Remove an option with DELETE .../options/{option_id}. This is permanent.

Options can't be managed on FREE_TEXT fields, or on custom fields created by an accounting integration — those values are owned by the integration.

3. Control which budgets use the field

If you created the field with budget_setting: SOME, link it to specific budgets:

  • GET /v1/businesses/{client_id}/custom-fields/{custom_field_id}/budgets — list linked budgets
  • POST .../budgets — link a budget
  • DELETE .../budgets/{budget_id} — unlink a budget

What happens next

The field and its options appear for your team when they complete expenses on the linked budgets. Schedule or event-trigger your sync so values stay current with your ERP.

Related articles