Create Family
create_familyCreate a family record linking a father, mother, children, and family events such as marriage. Use it to add a couple with relationship type and child references after those people and events exist.
Instructions
Create a family: a couple (father and mother, each optional) with their relationship type, children and family events such as Marriage. People and events must already exist (create_person, create_event). Gramps Web links the father, mother and children back to the family in the same save, and if one of them does not exist it refuses the family and nothing is saved. relationshipType stays Unknown unless a source records the marriage: then pass Married and link the Marriage event in eventRefs, where a family event takes the Family role, which is what makes Gramps and Gramps Web show the family among the event's participants. Each child in childRefs carries its own relation to the father and to the mother, Birth unless the source says Adopted, Stepchild or another; children keep the order given, so list them by birth. Citations, notes, media, tags and attributes passed here belong to the family itself, not to its members or events. Returns the new handle, Gramps ID and stored relationship type; when children or events were left out, it also lists the update_family calls that add them with linkMode add. Does not check for duplicates: look at the parents' families first, and change an existing family with update_family. Children are added here through childRefs, not through the child's parentFamilyHandles. For several new records that link to each other, such as the people, events, source and citation of one register entry, use create_records instead: one transaction, all created or none. Writes run one at a time and need a Gramps Web account allowed to edit the tree; a locked or rate-limited write fails with the delay to wait before retrying it. Formats of every argument: get_reference(topic: "input-guide").
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| childRefs | No | Children, each with its relation to the father and mother (Birth by default; Adopted, Stepchild, …). Child references (handles, not Gramps IDs): JSON array of {ref, frel, mrel}, strings "HANDLE::RelType" (sets both frel and mrel; default: Birth), comma/pipe/newline-separated, or a single handle. A relation must be a standard Gramps one (Birth, Adopted, Stepchild, Sponsored, Foster, Unknown, None) or a custom one the tree already uses. JSON objects accept snake_case (frel, mrel, tag_list) or camelCase (fatherRel, tagList, etc.). | |
| eventRefs | No | Existing family events such as Marriage or Divorce. Event references (handles, not Gramps IDs): JSON array of {ref, role}, strings "HANDLE::Role" (default role: Primary on a person, Family on a family), comma/pipe/newline-separated, or a single handle. A role must be a standard Gramps role or a custom one the tree already uses; anything else is rejected with suggestions. JSON objects accept snake_case or camelCase list fields (note_list / noteList). | |
| isPrivate | No | Mark the family private (default false). | |
| attributes | No | Attributes: JSON array of objects {type,value,...}, or strings "Type: Value" (first colon), or one string with lines or | between entries. A type must be a standard Gramps attribute type or a custom one the tree already uses; anything else is rejected with suggestions. Full grammar: gramps://input-guide. | |
| tagHandles | No | Tags. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| noteHandles | No | Notes. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| fatherHandle | No | The father, optional. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| mediaHandles | No | Media. Media handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string. To show only part of an image, such as one record on a page scan, give an object {"ref":"…","region":[left, top, right, bottom]} in place of the handle. A region is [left, top, right, bottom]: its edges in percent of the image width and height, 0 to 100, measured from the top-left corner; [10, 20, 60, 45] runs from 10% to 60% across and from 20% to 45% down. [0, 0, 100, 100] shows the whole image again; read_media with the same region shows what it covers. | |
| motherHandle | No | The mother, optional. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| citationHandles | No | Citations. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| relationshipType | No | Relationship type: Married, Unmarried, Civil Union or Unknown (default, as in Gramps). Pass Married when a source records the marriage. Must be a standard Gramps type or a custom one the tree already uses; anything else is rejected with suggestions. List: get_reference(topic: "types"). | Unknown |