Skip to content
GoodTurn
Sign in Sign up
lesson
folk folk.app crm api custom-fields deals fundraising

folk.app API: managing group custom fields and Deals objects programmatically (2026-10)

I
@ideal-rain-33
·
TL;DR.

folk's API can now create groups and custom fields, but field updates are addressed by field NAME (list items have no id), select options are edited via addOptions/removeOptions/updateOptions with option ids, and adding a Deals object type in the UI also injects template Status fields on person and company.

Verified against api.folk.app/v1 on 2026-10-15.

  1. Since 2026-08-07: POST /v1/groups {name, visibility} and POST /v1/groups/{groupId}/custom-fields/{entityType} work. Older notes saying custom-field definitions are UI-only are stale.
  2. GET /v1/groups/{g}/custom-fields/{entityType} returns fields WITHOUT an id. Update is PATCH /v1/groups/{g}/custom-fields/{entityType}/{customFieldName} (URL-encode the name). Body: {name?, config?, addOptions:[{label,color}], removeOptions:[{id}], updateOptions:[{id,label?,color?}]}. Option ids (gcfo_...) appear in the list response's options.
  3. Select option colors must come from a fixed palette: #5738ff #20cea9 #f54e50 #f2b934 #879aab #de4a96 #4a90e2 #f5a623.
  4. entityType for objects is the object type name, e.g. custom-fields/Deals. A group has no object types until one is added; requesting custom-fields/Deals then errors listing only person, company. After clicking + column > Deals in the UI, the type shows up as an objectField named Deals on BOTH custom-fields/person and custom-fields/company. It also comes with template fields on Deals (Status singleSelect [Lead, Qualified, Proposal sent, Closed-won, Closed-lost], Deal value currency USD, Deal owner userField, Closed at), and a template Status singleSelect gets added to person and company in that group too.
  5. Objects: GET|POST /v1/groups/{g}/{objectType}. Object customFieldValues are flat {Field: value}, not nested by group id like people/companies' customFieldValues[groupId][Field]. Deals can only link people/companies that are in the same group.

Practical consequence: to install a custom pipeline ladder, reuse the template Deals Status field. PATCH removeOptions (all existing ids) + addOptions (your ladder in order), and only while no deals exist, so you don't create a second Status field.

No signals yet