📘

Availability

The Custom Fields API is part of Wafeq Public API v1 and is available to organizations on the Plus plan and above.

Custom Fields

Custom fields let you attach organization-defined data to Wafeq resources such as invoices, bills and contacts. Each custom field has a type (text, number, date, select, …) and is scoped to one or more resource groups it applies to.

This guide walks you through:

1. The custom field data model
2. Supported field types and the resources they can attach to
3. Managing custom field definitions via /v1/custom-fields/
4. Reading and writing custom field values on documents and line items
5. Validation rules and common gotchas

Base URL & authentication

All examples in this guide use the Wafeq Public API v1 base URL:

https://api.wafeq.com/v1/

Every request must include your Wafeq API key — see Get your API Key:

Authorization: Api-Key <YOUR_API_KEY>

1. The custom field data model

A custom field is an organization-scoped definition. It does not store values itself — instead, each resource that it applies to carries a custom_fields JSON object that maps the custom field ID to the value entered for that resource.

2. Field types and apply-to groups

Supported field types (config.field_type)

Apply-to groups (apply_to)

Each custom field can target one or more of the following groups. The same custom field is automatically available on every resource belonging to the selected groups (and on their line items when is_line_item_field = true).

📘

Supported groups

Only SALES, PURCHASES and CONTACTS are currently exposed through the Public API v1. Additional groups may be enabled in future versions.

3. Managing custom field definitions

Custom field definitions live at:

https://api.wafeq.com/v1/custom-fields/

The endpoint supports the standard CRUD verbs:

Create example

curl -X POST "https://api.wafeq.com/v1/custom-fields/" \
  -H "Authorization: Api-Key $WAFEQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Department",
    "name_ar": "القسم",
    "apply_to": ["SALES", "PURCHASES"],
    "config": {
      "field_type": "SELECT",
      "metadata": {
        "choices": [
          {"label": "Sales"},
          {"label": "Operations"}
        ]
      }
    },
    "is_active": true,
    "is_required": false,
    "is_line_item_field": false
  }'

Create response

{
  "id": "cf_abc123",
  "name": "Department",
  "name_ar": "القسم",
  "field_type": "SELECT",
  "apply_to": ["SALES", "PURCHASES"],
  "config": {
    "field_type": "SELECT",
    "metadata": {
      "choices": [
        { "label": "Sales", "value": "sales" },
        { "label": "Operations", "value": "operations" }
      ]
    }
  },
  "is_active": true,
  "is_required": false,
  "is_line_item_field": false,
  "created_ts": "2026-04-17T10:30:00Z",
  "modified_ts": "2026-04-17T10:30:00Z"
}

💡

SELECT choices

When you create or update a SELECT custom field, you may pass choices with only a label. Wafeq will automatically generate a stable value that you should use when writing the custom field value onto documents.

4. Reading and writing custom field values on documents

Every resource that supports custom fields exposes a custom_fields object. Keys are custom field IDs (cf_…); values follow the field's declared type.

Example: invoice with custom field values

{
  "id": "inv_9ykZ2t3sC4nMfJpN",
  "contact": "co_VGaNjD4ksaCUTEveaVyPMo",
  "invoice_date": "2026-04-17",
  "custom_fields": {
    "cf_abc123": "sales",
    "cf_def456": "2026-05-01"
  },
  "line_items": [
    {
      "description": "Consulting",
      "unit_amount": 1000,
      "quantity": 1,
      "custom_fields": {
        "cf_ghi789": "Project Alpha"
      }
    }
  ]
}

• Document-level custom fields (is_line_item_field = false) appear under the top-level custom_fields object.
• Line-item custom fields (is_line_item_field = true) appear under custom_fields on each line item of SALES and PURCHASES documents. CONTACTS have no line items.

Writing values

Send the same custom_fields object on create/update. Only IDs for active, non-deleted custom fields that actually apply_to this resource are respected — any other keys in the payload are stripped silently.

{
  "custom_fields": {
    "cf_abc123": "sales",
    "cf_def456": "2026-05-01"
  }
}

5. Validation rules

When you write values onto a document or line item, Wafeq validates each entry against its custom field definition:

Updating a custom field definition has additional safeguards:

• You cannot change field_type on a custom field that has values stored on any existing document.
• You cannot remove a SELECT choice that is currently used by at least one document.
• You cannot remove an apply_to group while documents in that group still reference the field.

🚧

Deleting a custom field

DELETE /v1/custom-fields/{id}/ fails while any document still stores a value for the field. Use is_active = false to retire a custom field without removing historical values.

6. Quick recipe

1. POST /v1/custom-fields/ — define, for example, a SELECT field called Department on SALES and PURCHASES.
2. GET /v1/custom-fields/ — copy the returned id (e.g. cf_abc123) and the values from config.metadata.choices.
3. POST /v1/invoices/ — include "custom_fields": {"cf_abc123": "sales"} on the payload.
4. GET /v1/invoices/{id}/ — the same custom_fields object is echoed back on every read.

That's it. You now have typed, validated organization-defined metadata flowing through the Wafeq API and the UI together.