CompanyCustomFields

Add an option to a custom field

Adds a value to the options of this custom field, for one customer or, without customer_id, common to every customer. Use it to seed a catalogue before the first invoice; values used on invoices are added on their own.

  • Equivalent values: two values are equivalent when they match ignoring case, accents and repeated spaces. If the field already has an equivalent option — of that customer or a common one — no option is created: the response is 200 with the existing option, and its text is kept. Only when nothing equivalent exists is the option created, with 201.
  • Archived options: an equivalent archived option counts as existing. It comes back with 200 and stays archived; reactivate it with PATCH /v1/companies/{company_id}/custom-fields/{key}/options/{option_id}.
  • Suggestions off: a field with suggest_values: false accepts options in the same way, so a catalogue can be prepared before turning suggestions on. They are not offered on invoices while the setting is off.
post/v1/companies/{company_id}/custom-fields/{key}/options

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/companies/{company_id}/custom-fields/{key}/options
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Idempotency key to prevent duplicates in sensitive operations.

  • Any unique client-generated string (e.g. an order id). A UUID also works but is not required
  • Allowed characters: letters, digits, _ and - (max 255 chars)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses expire 24 hours after processing

The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.

Request body

valuestring required

Text of the option. Leading and trailing spaces are removed; a value that is empty after that answers 422. Two values are equivalent when they match ignoring case, accents and repeated spaces (Gran Via 12 and gran vía 12).

customer_idstring uuid

Customer of the company the option belongs to. Omit it for an option common to every customer.

Example request

{
  "value": "Gran Vía 12",
  "customer_id": "4f244735-980b-4d9c-80e8-6331fa0b1958"
}

Response

An equivalent option already existed; this is that option, unchanged.

successboolean required

Example response

{
  "success": true,
  "data": {
    "id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
    "value": "Gran Vía 12",
    "customer_id": "4f244735-980b-4d9c-80e8-6331fa0b1958"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.