Create Person
create_personCreate one person with full control: names, gender, links to existing events (with roles), families, citations, notes, media and tags, plus attributes, addresses, URLs and associations.
Instructions
Create one person with full control: names, gender, links to existing events (with roles), families, citations, notes, media and tags, plus attributes, addresses, URLs and associations. Returns the new handle, Gramps ID and name, with next steps. Does not check for duplicates: search for the person first, and change an existing person with update_person. Events are separate records: create the Birth, Death and other events with create_event first and pass them in eventRefs, or attach them later with update_person (linkMode add). To make the person a child of a family, add them to the family's childRefs (create_family or update_family). Formats of every argument: get_reference(topic: "input-guide").
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| urls | No | URLs: JSON array of {type,path,desc}, or strings "Web Home: https://…" with optional " — note" after URL, or lines/| separated. A type must be a standard Gramps URL type (E-mail, Web Home, Web Search, FTP, Unknown) or a custom one the tree already uses. Grammar: gramps://input-guide. | |
| gender | No | Gender: Female, Male, or Unknown (default Unknown). | Unknown |
| addresses | No | Addresses: JSON array of Gramps address objects; or text blocks with lines like street:, city:, … (blank line or --- between addresses); or one plain line = street only. Grammar: gramps://input-guide. | |
| eventRefs | No | Existing events this person takes part in, each with a role (Primary by default; Witness, Godparent, …). Event references (handles, not Gramps IDs): JSON array of {ref, role}, strings "HANDLE::Role" (default role: Primary), 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 person 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":"…"}. | |
| primaryName | Yes | Name: full Gramps name JSON (see gramps://input-guide), a plain string ("Married Name:: Jane|Smith"), or a simple object. Prefer a JSON object (not a quoted JSON string) when using structured name parts. Object fields: given/first (given name), surname/last (primary surname value), prefix/surname_prefix (particle before surname: von, de, van, del…), connector/surname_connector (joins compound surnames: - or y), origin_type/surname_origin (Gramps OriginType for the primary surname: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Unknown), patronymic (shortcut: stored as a separate Patronymic surname entry), matronymic (shortcut: stored as a separate Matronymic surname entry), title (Dr./Prof./Sir), suffix (Jr./Sr./III/PhD), call (preferred call name), nick/nickname, famnick/family_nick, type (name type: Birth Name/Married Name/Also Known As/…). Name types and origins must be standard Gramps ones or custom ones the tree already uses. Plain full-name strings (name/text/full or "Given Middle Surname") only split into given + surname; they cannot create structured name parts such as patronymic, matronymic, prefix, connector, origin_type, title, suffix, call, nick, or famnick. Use object fields or native surname_list instead. For complex multi-surname cases use native Gramps surname_list format. Also accepts: name/text/full as a full-name string with optional type field. | |
| mediaHandles | No | Media. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| familyHandles | No | Families where this person is a parent or spouse. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| alternateNames | No | Alternate names: array of strings ("Married Name:: Jane|Smith"), simple objects, or full Gramps name objects. Object fields: given/first, surname/last, prefix/surname_prefix (von/de/van), connector/surname_connector, origin_type/surname_origin (Gramps OriginType: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Unknown), patronymic (→ separate Patronymic surname entry), matronymic (→ separate Matronymic surname entry), title, suffix (Jr./Sr./III), call, nick, famnick, type (name type). Name types and origins must be standard Gramps ones or custom ones the tree already uses. For multi-surname names use native surname_list format. Multiple names in one string: separate with newlines (not |). | |
| 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":"…"}. | |
| personAssociations | No | Person associations (handles, not Gramps IDs): JSON array of {ref, rel, ...}, or strings "PERSON_HANDLE:: Godfather" (double colon after handle). JSON objects accept rel or relationship, and snake_case or camelCase list fields (note_list / noteList). Grammar: gramps://input-guide. | |
| parentFamilyHandles | No | Families where this person is a child. Does not add the person to the family's children: use childRefs on the family for that. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. |