Skip to main content

How to manage custom fields and values via the OpenAPI

  • Updated

The Weel OpenAPI lets you create custom fields and sync their values with your source system automatically, with no cap on values (see Getting started with the Weel OpenAPI).

Before you start

You will need:

  • Custom Fields enabled on your plan (Premium or Enterprise) and API access enabled for your business, included with Enterprise. Contact your account manager (or success@letsweel.com) if you're not sure whether your business has API access.
  • Owner or Admin access, or a custom role with the API permission, to generate an API key. See How to generate and manage API keys. This only gates generating the key: the endpoints below authenticate at the business level, not per user, once you have a valid key.
  • Your business's Client ID / business ID, shown on Settings > API in the Weel web app.

Steps

Include your API key as a bearer token in the Authorization header of every request, and pass your business ID as a query parameter (?business_id=...) rather than in the URL path. The full endpoint reference is at developer.letsweel.com.

  1. Create a custom field.

    Send POST /public/v1/custom-fields?business_id={business_id} with:

    • name: the display name (for example, "Project Code"), up to 64 characters. Uniqueness within your business is an exact, case-sensitive match, so agree on a naming convention with your team to avoid near-duplicates like "Project Code" and "project code".
    • field_type: LIST for a field with selectable options, or FREE_TEXT for open entry.
    • budget_setting (optional): ALL_CURRENT_AND_NEW (default), SOME, or NONE.
    • is_manager_only (optional, defaults to false): restricts the field to budget managers only, rather than every cardholder. This can't be changed after the field is created, so decide upfront.

    Update a field with PATCH /public/v1/custom-fields/{custom_field_id}?business_id={business_id}, or delete it with DELETE on the same path. Deleting a field removes all of its options and budget links, and triggers a background recheck of your business's expense-completion status. If the field was created by an accounting integration, you can only update its budget_setting here: its name and field_type are locked and can only change from the integration side.

  2. Sync the field's values.

    For LIST fields, manage the selectable options:

    • Add an option with POST /public/v1/custom-fields/{custom_field_id}/options?business_id={business_id}. There's no cap on the number of options, and option text can be up to 128 characters.
    • Rename an option with PATCH .../options/{option_id}?business_id={business_id}.
    • Remove an option with DELETE .../options/{option_id}?business_id={business_id}. This is permanent.

    You can't add, rename, or delete options on FREE_TEXT fields, or on custom fields created by an accounting integration (Xero, MYOB, QuickBooks, NetSuite, or Business Central): those options are owned and synced by the integration. Instead, you can enable or disable an existing synced option (PATCH with "enabled": true/false). Options you create yourself through this API can't be toggled this way; deleting is the only way to remove one. A field's created_by value tells you which case you're in: MANUAL (created in-app), PUBLIC_API (created through this API), or the name of the accounting integration that owns it.

  3. Control which budgets use the field.

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

    • GET /public/v1/custom-fields/{custom_field_id}/budgets?business_id={business_id}: list linked budgets.
    • POST .../budgets?business_id={business_id}: link a budget. It must belong to the same business, and linking the same budget twice is rejected.
    • DELETE .../budgets/{budget_id}?business_id={business_id}: unlink a budget. This also triggers a background expense-completion recheck.

    These budget-link endpoints only work while budget_setting is SOME. If you switch to ALL_CURRENT_AND_NEW or NONE, any existing budget links aren't automatically cleared, so switch back to SOME first if you need to review or remove them. List endpoints across all three sections are paginated, returning count, next, previous, and a results array, with up to 500 items per page.

What happens next

Your custom 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 source system.

Related articles