diff --git a/docs/api/v4/custom-data.md b/docs/api/v4/custom-data.md new file mode 100644 index 0000000000000000000000000000000000000000..e98e74f09189de31ebbd0a20b1e61a7c36585c43 --- /dev/null +++ b/docs/api/v4/custom-data.md @@ -0,0 +1,21 @@ +# APIv4 and Custom Data + +CiviCRM has a flexible custom data system which allows nearly any entity to be extended. It comes in two distinct flavors: Single-record and Multi-record. For more background see the user guide chapter: [Creating Custom Fields](https://docs.civicrm.org/user/en/latest/organising-your-data/creating-custom-fields/). + +## Single-Record Custom Data + +Because single-record fields extend an entity 1-to-1, the API treats the custom fields as an extension of the regular fields. For example, normally an Event has fields like `id`, `title`, `start_date`, `end_date`, etc. Adding a custom group named "Event_Extra" and a field named "Room_number" would be accessible from the API as "Event_Extra.Room_number". You would retrieve it and set it as if it were any other field. Note that the `name` of a field is not to be confused with the `label` The API refers to custom groups/fields by name and not user-facing labels which are subject to translation and alteration. + +For setting custom date fields, date format is anything understood by `strtotime`, e.g. "now" or "-1 week" or "2020-12-25". + +## Multi-Record Custom Data + +Multiple record custom data sets are treated by the API as entities, which work similarly to other entities attached to contacts (Phone, Email, Address, etc.). For example, creating a multi-record set named "Work_History" could then be accessed via the API as an entity named "Custom_Work_History". Creating a record would be done like so: + +```php +civicrm_api4('Custom_Work_history', 'create', $params); +``` + +## Try It Out + +Once you have created some custom data in your system, look for it in the API explorer. Single-record data will appear as fields on the entities they extend, and multi-record data will appear in the list of entities (look under "C" alphabetically as they all start with the prefix "Custom_". diff --git a/mkdocs.yml b/mkdocs.yml index a9424f0b4779a18bfc282a9ef43c2fc142ec4f2f..19142b4c956f35aeaa269a3254fed042b4e6505e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -57,7 +57,7 @@ pages: # - APIv4 Options: api/v4/options.md - APIv4 Joins: api/v4/joins.md - APIv4 Chaining: api/v4/chaining.md - # - APIv4 Custom Data: api/v4/custom-data.md + - APIv4 Custom Data: api/v4/custom-data.md # - APIv4 Examples: api/v4/examples.md # - APIv4 Changes: api/v4/changes.md - APIv3: