Custom fields

Base path: /api/v1/members/{memberId}/custom-fields. Definitions and values are scoped to a member you own. Authentication uses the customFields API key scope only (customFields: read or read_write) (customFields: read or read_write): not the members scope, even though the URL contains /members/.

See Scopes for the customFields key and Errors for shared JSON error shape.

Field types and values

type on each definition is one of: text, markdown, color, date, birthday, day_month, month_year, year, tags, url, image, photo_gallery, featured_song, featured_playlist, separator.

• text, markdown, color, date, day_month, month_year, year, url, image, featured_song, featured_playlist: use a JSON string use a JSON string in PUT .../value. Empty string removes the stored value. Featured Spotify fields require a Spotify resource id.
• tags, photo_gallery: use a JSON array of strings. Empty array clears the value.
• separator: visual divider; value is usually null.

In list and patch responses, value is string, string[] (for tags), or null when unset. Markdown fields may rewrite external image URLs on save (same behaviour as the app).

List custom fields

GET/api/v1/members/{memberId}/custom-fields

Returns active definitions for the member, ordered by orderIndex, each with coerced value. Trashed members return [].

Response

200: JSON array. Each element includes definition columns plus value (example shape):

{
  "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "userId": "a0a0a0a0-a0a0-a0a0-a0a0-a0a0a0a0a0a0",
  "memberId": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
  "label": "Notes",
  "icon": "file-text",
  "type": "markdown",
  "orderIndex": 0,
  "description": null,
  "required": false,
  "deletedAt": null,
  "purgeAt": null,
  "value": "## Hello"
}

Examples

cURL

curl -sS \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/members/MEMBER_ID/custom-fields"

JavaScript (fetch)

const res = await fetch("https://api.floralitys.com/api/v1/members/MEMBER_ID/custom-fields", {
  headers: { Authorization: "Bearer YOUR_TOKEN" },
});
if (!res.ok) throw new Error(await res.text());
const fields = await res.json();

Status codes

• 200: JSON array
• 400 / 404: bad member id or member not found
• 401 / 403: auth / missing customFields: read

Create definition

POST/api/v1/members/{memberId}/custom-fields

Strict JSON: label (string), type (see table above), orderIndex (integer). Optional: description, required, insertAtStart (boolean; when true, shifts existing fields and inserts at index 0).

Response

201: { "id": "<uuid>" }

{
  "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890"
}

Examples

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"Favourite colour","type":"color","orderIndex":0}' \
  "https://api.floralitys.com/api/v1/members/MEMBER_ID/custom-fields"

Status codes

• 201: created id
• 400: validation, limit reached, member in trash, invalid body
• 404: member not found
• 401 / 403: missing customFields: read_write

Update definition

PATCH/api/v1/members/{memberId}/custom-fields/{fieldId}

Strict JSON: optional label, icon (string or null), orderIndex, description (string or null). At least one field required. Custom field icons may require a Pro plan (same as the app).

Response

200: single definition object with value (same shape as list items).

Examples

curl -sS -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"Favourite colour (updated)"}' \
  "https://api.floralitys.com/api/v1/members/MEMBER_ID/custom-fields/FIELD_ID"

Status codes

• 200: updated row
• 400: empty body, unknown keys, field in trash, validation
• 404: field or member not found / wrong member for field id
• 401 / 403: missing write scope

Delete definition (soft)

DELETE/api/v1/members/{memberId}/custom-fields/{fieldId}

Moves the definition to trash (retention same as rest of product). 204 No Content on success.

Examples

curl -sS -X DELETE \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/members/MEMBER_ID/custom-fields/FIELD_ID"

Status codes

• 204: success
• 400: already in trash
• 404: not found / wrong member
• 401 / 403: missing write scope

Set value

PUT/api/v1/members/{memberId}/custom-fields/{fieldId}/value

Strict JSON: { "value": string | string[] }. Must match the field type (e.g. tags need an array). Clearing uses "" or [] as appropriate. 204 No Content on success.

Examples

curl -sS -X PUT \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value":"#FF00AA"}' \
  "https://api.floralitys.com/api/v1/members/MEMBER_ID/custom-fields/FIELD_ID/value"

curl -sS -X PUT \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value":["one","two"]}' \
  "https://api.floralitys.com/api/v1/members/MEMBER_ID/custom-fields/FIELD_ID/value"

Status codes

• 204: success
• 400: wrong type for value, validation, field in trash, member in trash
• 404: field or member not found / mismatch
• 401 / 403: missing write scope

Reorder definitions

POST/api/v1/members/{memberId}/custom-fields/reorder

Strict JSON: updates: non-empty array of { "id", "orderIndex" }. Every id must belong to this member. 204 on success.

Examples

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"updates":[{"id":"uuid-a","orderIndex":0},{"id":"uuid-b","orderIndex":1}]}' \
  "https://api.floralitys.com/api/v1/members/MEMBER_ID/custom-fields/reorder"

Status codes

• 204: success
• 400: empty updates, field in trash, validation
• 404: member or field not found / wrong member
• 401 / 403: missing write scope

Restore definition

POST/api/v1/members/{memberId}/custom-fields/{fieldId}/restore

Restores a trashed definition. 204 on success.

Examples

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/members/MEMBER_ID/custom-fields/FIELD_ID/restore"

Status codes

• 204: success
• 400: not in trash
• 404: not found / wrong member
• 401 / 403: missing write scope