Create Person
create_personCreate a Gramps Web person with names, events, families, citations, notes and media, and check for possible duplicates before adding the record.
Instructions
Create one person: names, gender, links to existing events with the person's role in each, families, citations, notes, media and tags, plus attributes, addresses, URLs and associations. Returns the new handle, Gramps ID and name, with next steps. Checks the tree for the same person first: someone with the same given name and surname (spelling variants, old letters, Cyrillic and Latin letters, and male, female and daughter's forms such as Novák, Nováková and Новак count as one), not the other gender, without another patronymic, and born within two years, or a child of the same parents when there are no two years to compare, stops the call with action "refused" and the possible duplicates; namesakes born up to five years apart, or without a year, are listed after the person is created. Add to an existing person with update_person; create a different person anyway with notDuplicateOf. primaryName is the main name, usually the birth name, e.g. {"given": "Ivan", "patronymic": "Petrovich", "surname": "Sidorov"}; a married name or another spelling goes in alternateNames. 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). The first Birth and the first Death in the Primary role, the default, become the person's birth and death in Gramps; in another role, such as Witness, the event is only linked. familyHandles and parentFamilyHandles link the person to a family but not the family to the person: name the person in the family's fatherHandle, motherHandle or childRefs instead (create_family or update_family), which links both ways. 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 |
|---|---|---|---|
| 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 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 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: a plain string ("Married Name:: Jane|Smith", "Given Middle Surname") or a JSON object (not a quoted JSON string). Object fields: given (or first_name), surname (primary surname value), prefix (particle before the surname: von, de, van, del…), connector (joins compound surnames: - or y), origin_type (Gramps OriginType of that surname: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Unknown), patronymic and matronymic (each stored as a surname entry of its own with that origin), title (Dr./Prof./Sir), suffix (Jr./Sr./III/PhD), call (preferred call name), nick, famnick, type (name type: Birth Name/Married Name/Also Known As/…), name (the whole name as one string, instead of given and surname), and native Gramps fields such as surname_list for several surnames ([{surname, prefix, connector, origintype, primary}], see gramps://input-guide). Name types and origins must be standard Gramps ones or custom ones the tree already uses. camelCase forms (firstName, surnameList, originType) work too; any other field is an error, not ignored. A plain string only splits into given name and surname: use object fields for a patronymic, prefix, title and the like. | |
| 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. | |
| familyHandles | No | Families where this person is a parent or spouse. Does not make the person the family's father or mother: use fatherHandle or motherHandle 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":"…"}. | |
| alternateNames | No | Alternate names: array of strings ("Married Name:: Jane|Smith") or name objects. Object fields, as in primaryName: given (or first_name), surname, prefix (von/de/van), connector, origin_type (Gramps OriginType: Inherited, Given, Taken, Patronymic, Matronymic, Feudal, Pseudonym, Patrilineal, Matrilineal, Occupation, Location, Unknown), patronymic and matronymic (each a surname entry of its own), title, suffix (Jr./Sr./III), call, nick, famnick, type (name type), name (the whole name as one string), and native surname_list for several surnames. Name types and origins must be standard Gramps ones or custom ones the tree already uses. camelCase forms work too; any other field is an error, not ignored. Multiple names in one string: separate with newlines (not |). | |
| notDuplicateOf | No | People of the tree who are someone else, from the possible duplicates of a refused call: Gramps IDs or handles, e.g. ["I0012"]. The duplicate check passes over them. | |
| 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":"…"}. |