API reference

People

Read, create, edit, merge, unmerge and delete the people in a workspace; read a person's timeline, close family, tree and expected records; add and remove relatives.

Paths are relative to https://kleiobase.com/api/v1.

get/workspaces/{workspace_id}/people

List people

Each person carries folder_id and tag_ids.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
limit	query	no	Page size. Default 25, max 100.
cursor	query	no	The next_cursor of the previous page. Opaque.
q	query	no	Name search (accent-insensitive, max 200 characters).
folder_id	query	no	Only people in this folder.
tag_id	query	no	Only people with this tag.

Responses

200 A page of people. (PersonList)
401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
403 The account has no paid plan. (ErrorResponse)
404 The workspace does not exist or is not visible to this key's owner. Also: folder_id or tag_id is not in this workspace. (ErrorResponse)
422 Invalid limit, cursor, q, folder_id or tag_id, or folder_id is a folder of records. (ErrorResponse)
429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)

200 response schema

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "given_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "surname": {
            "type": [
              "string",
              "null"
            ]
          },
          "maiden_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "name_prefix": {
            "type": [
              "string",
              "null"
            ]
          },
          "name_suffix": {
            "type": [
              "string",
              "null"
            ]
          },
          "surname_prefix": {
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "nickname": {
            "type": [
              "string",
              "null"
            ]
          },
          "display_name": {
            "type": "string"
          },
          "gender": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "M",
                  "F",
                  "X",
                  "U"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "birth": {
            "type": "object",
            "properties": {
              "date": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "year": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": -9007199254740991,
                    "maximum": 9007199254740991
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "place": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "date",
              "year",
              "place"
            ]
          },
          "christening": {
            "type": "object",
            "properties": {
              "date": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "year": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": -9007199254740991,
                    "maximum": 9007199254740991
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "place": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "date",
              "year",
              "place"
            ]
          },
          "death": {
            "type": "object",
            "properties": {
              "date": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "year": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": -9007199254740991,
                    "maximum": 9007199254740991
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "place": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "cause": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "date",
              "year",
              "place",
              "cause"
            ]
          },
          "burial": {
            "type": "object",
            "properties": {
              "date": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "year": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": -9007199254740991,
                    "maximum": 9007199254740991
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "place": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "date",
              "year",
              "place"
            ]
          },
          "occupation": {
            "type": [
              "string",
              "null"
            ]
          },
          "religion": {
            "type": [
              "string",
              "null"
            ]
          },
          "living_status": {
            "type": [
              "string",
              "null"
            ]
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "folder_id": {
            "description": "The folder the person is in (null: none). Returned by GET .../people.",
            "anyOf": [
              {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
              },
              {
                "type": "null"
              }
            ]
          },
          "tag_ids": {
            "description": "Ids of the person's tags. Returned by GET .../people.",
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            }
          }
        },
        "required": [
          "id",
          "workspace_id",
          "given_name",
          "surname",
          "maiden_name",
          "name_prefix",
          "name_suffix",
          "surname_prefix",
          "title",
          "nickname",
          "display_name",
          "gender",
          "birth",
          "christening",
          "death",
          "burial",
          "occupation",
          "religion",
          "living_status",
          "notes",
          "created_at"
        ]
      }
    },
    "next_cursor": {
      "description": "Pass as ?cursor to get the next page. Null on the last page.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "data",
    "next_cursor"
  ]
}

post/workspaces/{workspace_id}/people

Create a person

Matching for the new person is queued, never run inline. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
Idempotency-Key	header	no	Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Request body (application/json, required)

{
  "type": "object",
  "properties": {
    "given_name": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "surname": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "maiden_name": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "nickname": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "gender": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "M",
            "F",
            "X",
            "U"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "birth_date": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 100
        },
        {
          "type": "null"
        }
      ]
    },
    "birth_place": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 300
        },
        {
          "type": "null"
        }
      ]
    },
    "death_date": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 100
        },
        {
          "type": "null"
        }
      ]
    },
    "death_place": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 300
        },
        {
          "type": "null"
        }
      ]
    },
    "occupation": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 300
        },
        {
          "type": "null"
        }
      ]
    },
    "religion": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "notes": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 10000
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "additionalProperties": false
}

Responses

201 The created person. (Person)
401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
403 The account has no paid plan, or the key is read-only (a read_write key is required). Also: the plan's person limit is reached. (ErrorResponse)
404 The workspace does not exist or is not visible to this key's owner. (ErrorResponse)
409 The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. (ErrorResponse)
422 Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. (ErrorResponse)
429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)

201 response schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "workspace_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "given_name": {
      "type": [
        "string",
        "null"
      ]
    },
    "surname": {
      "type": [
        "string",
        "null"
      ]
    },
    "maiden_name": {
      "type": [
        "string",
        "null"
      ]
    },
    "name_prefix": {
      "type": [
        "string",
        "null"
      ]
    },
    "name_suffix": {
      "type": [
        "string",
        "null"
      ]
    },
    "surname_prefix": {
      "type": [
        "string",
        "null"
      ]
    },
    "title": {
      "type": [
        "string",
        "null"
      ]
    },
    "nickname": {
      "type": [
        "string",
        "null"
      ]
    },
    "display_name": {
      "type": "string"
    },
    "gender": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "M",
            "F",
            "X",
            "U"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "birth": {
      "type": "object",
      "properties": {
        "date": {
          "type": [
            "string",
            "null"
          ]
        },
        "year": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "place": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "date",
        "year",
        "place"
      ]
    },
    "christening": {
      "type": "object",
      "properties": {
        "date": {
          "type": [
            "string",
            "null"
          ]
        },
        "year": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "place": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "date",
        "year",
        "place"
      ]
    },
    "death": {
      "type": "object",
      "properties": {
        "date": {
          "type": [
            "string",
            "null"
          ]
        },
        "year": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "place": {
          "type": [
            "string",
            "null"
          ]
        },
        "cause": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "date",
        "year",
        "place",
        "cause"
      ]
    },
    "burial": {
      "type": "object",
      "properties": {
        "date": {
          "type": [
            "string",
            "null"
          ]
        },
        "year": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "place": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "date",
        "year",
        "place"
      ]
    },
    "occupation": {
      "type": [
        "string",
        "null"
      ]
    },
    "religion": {
      "type": [
        "string",
        "null"
      ]
    },
    "living_status": {
      "type": [
        "string",
        "null"
      ]
    },
    "notes": {
      "type": [
        "string",
        "null"
      ]
    },
    "created_at": {
      "type": "string"
    },
    "folder_id": {
      "description": "The folder the person is in (null: none). Returned by GET .../people.",
      "anyOf": [
        {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        {
          "type": "null"
        }
      ]
    },
    "tag_ids": {
      "description": "Ids of the person's tags. Returned by GET .../people.",
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    }
  },
  "required": [
    "id",
    "workspace_id",
    "given_name",
    "surname",
    "maiden_name",
    "name_prefix",
    "name_suffix",
    "surname_prefix",
    "title",
    "nickname",
    "display_name",
    "gender",
    "birth",
    "christening",
    "death",
    "burial",
    "occupation",
    "religion",
    "living_status",
    "notes",
    "created_at"
  ]
}

get/workspaces/{workspace_id}/people/{person_id}

Get a person

The person plus the ids of their families and linked records.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
person_id	path	yes	The person id.

Responses

200 The person. (PersonDetail)
401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
403 The account has no paid plan. (ErrorResponse)
404 The workspace does not exist or is not visible to this key's owner. Also: The person does not exist, is in Trash, or is in another workspace. (ErrorResponse)
429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)

200 response schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "workspace_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "given_name": {
      "type": [
        "string",
        "null"
      ]
    },
    "surname": {
      "type": [
        "string",
        "null"
      ]
    },
    "maiden_name": {
      "type": [
        "string",
        "null"
      ]
    },
    "name_prefix": {
      "type": [
        "string",
        "null"
      ]
    },
    "name_suffix": {
      "type": [
        "string",
        "null"
      ]
    },
    "surname_prefix": {
      "type": [
        "string",
        "null"
      ]
    },
    "title": {
      "type": [
        "string",
        "null"
      ]
    },
    "nickname": {
      "type": [
        "string",
        "null"
      ]
    },
    "display_name": {
      "type": "string"
    },
    "gender": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "M",
            "F",
            "X",
            "U"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "birth": {
      "type": "object",
      "properties": {
        "date": {
          "type": [
            "string",
            "null"
          ]
        },
        "year": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "place": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "date",
        "year",
        "place"
      ]
    },
    "christening": {
      "type": "object",
      "properties": {
        "date": {
          "type": [
            "string",
            "null"
          ]
        },
        "year": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "place": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "date",
        "year",
        "place"
      ]
    },
    "death": {
      "type": "object",
      "properties": {
        "date": {
          "type": [
            "string",
            "null"
          ]
        },
        "year": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "place": {
          "type": [
            "string",
            "null"
          ]
        },
        "cause": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "date",
        "year",
        "place",
        "cause"
      ]
    },
    "burial": {
      "type": "object",
      "properties": {
        "date": {
          "type": [
            "string",
            "null"
          ]
        },
        "year": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "place": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "date",
        "year",
        "place"
      ]
    },
    "occupation": {
      "type": [
        "string",
        "null"
      ]
    },
    "religion": {
      "type": [
        "string",
        "null"
      ]
    },
    "living_status": {
      "type": [
        "string",
        "null"
      ]
    },
    "notes": {
      "type": [
        "string",
        "null"
      ]
    },
    "created_at": {
      "type": "string"
    },
    "folder_id": {
      "description": "The folder the person is in (null: none). Returned by GET .../people.",
      "anyOf": [
        {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        {
          "type": "null"
        }
      ]
    },
    "tag_ids": {
      "description": "Ids of the person's tags. Returned by GET .../people.",
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    },
    "family_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    },
    "record_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    }
  },
  "required": [
    "id",
    "workspace_id",
    "given_name",
    "surname",
    "maiden_name",
    "name_prefix",
    "name_suffix",
    "surname_prefix",
    "title",
    "nickname",
    "display_name",
    "gender",
    "birth",
    "christening",
    "death",
    "burial",
    "occupation",
    "religion",
    "living_status",
    "notes",
    "created_at",
    "family_ids",
    "record_ids"
  ]
}

patch/workspaces/{workspace_id}/people/{person_id}

Update a person

At least one field is required. Pending matches are re-scored; new match candidates are found by the scheduled run. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
person_id	path	yes	The person id.
Idempotency-Key	header	no	Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Request body (application/json, required)

{
  "type": "object",
  "properties": {
    "given_name": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "surname": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "maiden_name": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "nickname": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "gender": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "M",
            "F",
            "X",
            "U"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "birth_date": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 100
        },
        {
          "type": "null"
        }
      ]
    },
    "birth_place": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 300
        },
        {
          "type": "null"
        }
      ]
    },
    "death_date": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 100
        },
        {
          "type": "null"
        }
      ]
    },
    "death_place": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 300
        },
        {
          "type": "null"
        }
      ]
    },
    "occupation": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 300
        },
        {
          "type": "null"
        }
      ]
    },
    "religion": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "notes": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 10000
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "additionalProperties": false
}

Responses

200 The updated person. (Person)
401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
403 The account has no paid plan, or the key is read-only (a read_write key is required). (ErrorResponse)
404 The workspace does not exist or is not visible to this key's owner. Also: The person does not exist or is not visible. (ErrorResponse)
409 The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. (ErrorResponse)
422 Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. (ErrorResponse)
429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)

200 response schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "workspace_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "given_name": {
      "type": [
        "string",
        "null"
      ]
    },
    "surname": {
      "type": [
        "string",
        "null"
      ]
    },
    "maiden_name": {
      "type": [
        "string",
        "null"
      ]
    },
    "name_prefix": {
      "type": [
        "string",
        "null"
      ]
    },
    "name_suffix": {
      "type": [
        "string",
        "null"
      ]
    },
    "surname_prefix": {
      "type": [
        "string",
        "null"
      ]
    },
    "title": {
      "type": [
        "string",
        "null"
      ]
    },
    "nickname": {
      "type": [
        "string",
        "null"
      ]
    },
    "display_name": {
      "type": "string"
    },
    "gender": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "M",
            "F",
            "X",
            "U"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "birth": {
      "type": "object",
      "properties": {
        "date": {
          "type": [
            "string",
            "null"
          ]
        },
        "year": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "place": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "date",
        "year",
        "place"
      ]
    },
    "christening": {
      "type": "object",
      "properties": {
        "date": {
          "type": [
            "string",
            "null"
          ]
        },
        "year": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "place": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "date",
        "year",
        "place"
      ]
    },
    "death": {
      "type": "object",
      "properties": {
        "date": {
          "type": [
            "string",
            "null"
          ]
        },
        "year": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "place": {
          "type": [
            "string",
            "null"
          ]
        },
        "cause": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "date",
        "year",
        "place",
        "cause"
      ]
    },
    "burial": {
      "type": "object",
      "properties": {
        "date": {
          "type": [
            "string",
            "null"
          ]
        },
        "year": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "place": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "date",
        "year",
        "place"
      ]
    },
    "occupation": {
      "type": [
        "string",
        "null"
      ]
    },
    "religion": {
      "type": [
        "string",
        "null"
      ]
    },
    "living_status": {
      "type": [
        "string",
        "null"
      ]
    },
    "notes": {
      "type": [
        "string",
        "null"
      ]
    },
    "created_at": {
      "type": "string"
    },
    "folder_id": {
      "description": "The folder the person is in (null: none). Returned by GET .../people.",
      "anyOf": [
        {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        {
          "type": "null"
        }
      ]
    },
    "tag_ids": {
      "description": "Ids of the person's tags. Returned by GET .../people.",
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    }
  },
  "required": [
    "id",
    "workspace_id",
    "given_name",
    "surname",
    "maiden_name",
    "name_prefix",
    "name_suffix",
    "surname_prefix",
    "title",
    "nickname",
    "display_name",
    "gender",
    "birth",
    "christening",
    "death",
    "burial",
    "occupation",
    "religion",
    "living_status",
    "notes",
    "created_at"
  ]
}

delete/workspaces/{workspace_id}/people/{person_id}

Move a person to Trash

No body. The person can be restored with POST .../trash/restore. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
person_id	path	yes	The person id.
Idempotency-Key	header	no	Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Responses

200 Moved to Trash. (Ok)
401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
403 The account has no paid plan, or the key is read-only (a read_write key is required). (ErrorResponse)
404 The workspace does not exist or is not visible to this key's owner. Also: The person does not exist or is not visible. (ErrorResponse)
409 The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. (ErrorResponse)
422 Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. (ErrorResponse)
429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)

200 response schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ]
}

post/workspaces/{workspace_id}/people/delete

Move many people to Trash

All or nothing: every id must be a live person in this workspace, or nothing is moved. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
Idempotency-Key	header	no	Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Request body (application/json, required)

{
  "type": "object",
  "properties": {
    "ids": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    }
  },
  "required": [
    "ids"
  ],
  "additionalProperties": false
}

Responses

200 Moved to Trash. (BulkTrashed)
401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
403 The account has no paid plan, or the key is read-only (a read_write key is required). (ErrorResponse)
404 The workspace does not exist or is not visible to this key's owner. Also: A person does not exist, is not visible, or is already in Trash. (ErrorResponse)
409 The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. (ErrorResponse)
422 Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid body: 1 to 100 UUIDs. (ErrorResponse)
429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)

200 response schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      },
      "description": "The ids moved to the Trash (all of the ones sent)."
    }
  },
  "required": [
    "ok",
    "ids"
  ]
}

get/workspaces/{workspace_id}/people/{person_id}/timeline

Get a person's timeline

Dated entries first (ascending), then undated. Not paginated.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
person_id	path	yes	The person id.

Responses

200 Timeline entries. (TimelineResponse)
401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
403 The account has no paid plan. (ErrorResponse)
404 The workspace does not exist or is not visible to this key's owner. Also: The person does not exist or is not visible. (ErrorResponse)
429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)

200 response schema

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string"
          },
          "date": {
            "type": [
              "string",
              "null"
            ]
          },
          "year": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "place": {
            "type": [
              "string",
              "null"
            ]
          },
          "person_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            }
          },
          "record_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "label": {
            "type": "string"
          }
        },
        "required": [
          "kind",
          "date",
          "year",
          "place",
          "person_ids",
          "record_id",
          "label"
        ]
      }
    }
  },
  "required": [
    "data"
  ]
}

post/workspaces/{workspace_id}/people/{person_id}/merge

Merge two people

The path person is the survivor; other_person_id is absorbed into it. To undo it, send the returned match_id to POST .../people/{person_id}/unmerge. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
person_id	path	yes	The person id.
Idempotency-Key	header	no	Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Request body (application/json, required)

{
  "type": "object",
  "properties": {
    "other_person_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "field_choices": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "enum": [
          "given_name",
          "surname",
          "birth_date",
          "birth_place",
          "death_date",
          "death_place",
          "gender",
          "maiden_name",
          "occupation",
          "religion",
          "burial_date",
          "burial_place",
          "christening_date",
          "christening_place",
          "death_cause",
          "name_prefix",
          "name_suffix",
          "surname_prefix",
          "nickname"
        ]
      },
      "additionalProperties": {
        "type": "string",
        "enum": [
          "survivor",
          "absorbed"
        ]
      }
    }
  },
  "required": [
    "other_person_id"
  ],
  "additionalProperties": false
}

Responses

200 Merged. Returns the surviving person. (PersonMerged)
401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
403 The account has no paid plan, or the key is read-only (a read_write key is required). (ErrorResponse)
404 The workspace does not exist or is not visible to this key's owner. Also: A person does not exist or is not visible. (ErrorResponse)
409 The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. (ErrorResponse)
422 Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Same person twice, a man and a woman, or a field_choices side with no value. (ErrorResponse)
429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)

200 response schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "match_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The merge's match. Pass it to POST /people/{id}/unmerge to undo the merge."
    },
    "survivor": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "workspace_id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "given_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "surname": {
          "type": [
            "string",
            "null"
          ]
        },
        "maiden_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "name_prefix": {
          "type": [
            "string",
            "null"
          ]
        },
        "name_suffix": {
          "type": [
            "string",
            "null"
          ]
        },
        "surname_prefix": {
          "type": [
            "string",
            "null"
          ]
        },
        "title": {
          "type": [
            "string",
            "null"
          ]
        },
        "nickname": {
          "type": [
            "string",
            "null"
          ]
        },
        "display_name": {
          "type": "string"
        },
        "gender": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "M",
                "F",
                "X",
                "U"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "birth": {
          "type": "object",
          "properties": {
            "date": {
              "type": [
                "string",
                "null"
              ]
            },
            "year": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                {
                  "type": "null"
                }
              ]
            },
            "place": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "date",
            "year",
            "place"
          ]
        },
        "christening": {
          "type": "object",
          "properties": {
            "date": {
              "type": [
                "string",
                "null"
              ]
            },
            "year": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                {
                  "type": "null"
                }
              ]
            },
            "place": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "date",
            "year",
            "place"
          ]
        },
        "death": {
          "type": "object",
          "properties": {
            "date": {
              "type": [
                "string",
                "null"
              ]
            },
            "year": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                {
                  "type": "null"
                }
              ]
            },
            "place": {
              "type": [
                "string",
                "null"
              ]
            },
            "cause": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "date",
            "year",
            "place",
            "cause"
          ]
        },
        "burial": {
          "type": "object",
          "properties": {
            "date": {
              "type": [
                "string",
                "null"
              ]
            },
            "year": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                {
                  "type": "null"
                }
              ]
            },
            "place": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "date",
            "year",
            "place"
          ]
        },
        "occupation": {
          "type": [
            "string",
            "null"
          ]
        },
        "religion": {
          "type": [
            "string",
            "null"
          ]
        },
        "living_status": {
          "type": [
            "string",
            "null"
          ]
        },
        "notes": {
          "type": [
            "string",
            "null"
          ]
        },
        "created_at": {
          "type": "string"
        },
        "folder_id": {
          "description": "The folder the person is in (null: none). Returned by GET .../people.",
          "anyOf": [
            {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            },
            {
              "type": "null"
            }
          ]
        },
        "tag_ids": {
          "description": "Ids of the person's tags. Returned by GET .../people.",
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          }
        }
      },
      "required": [
        "id",
        "workspace_id",
        "given_name",
        "surname",
        "maiden_name",
        "name_prefix",
        "name_suffix",
        "surname_prefix",
        "title",
        "nickname",
        "display_name",
        "gender",
        "birth",
        "christening",
        "death",
        "burial",
        "occupation",
        "religion",
        "living_status",
        "notes",
        "created_at"
      ]
    }
  },
  "required": [
    "ok",
    "match_id",
    "survivor"
  ]
}

get/workspaces/{workspace_id}/people/{person_id}/family

Get a person's parents, partners and children

Each relative comes with the family it is linked through. A partner entry with person_id null is a family the person heads alone.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
person_id	path	yes	The person id.

Responses

200 The person's close family. (FamilyContext)
401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
403 The account has no paid plan. (ErrorResponse)
404 The workspace does not exist or is not visible to this key's owner. Also: The person does not exist or is not visible. (ErrorResponse)
429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)

200 response schema

{
  "type": "object",
  "properties": {
    "parents": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "person_id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "family_id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "pedigree": {
            "description": "GEDCOM pedigree of the child link (ADOPTED, FOSTER, SEALING, OTHER, or BIRTH); null = biological.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "person_id",
          "family_id",
          "pedigree"
        ]
      }
    },
    "partners": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "person_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
              },
              {
                "type": "null"
              }
            ],
            "description": "The other partner. Null when the family has no second partner recorded, or the other partner is in Trash."
          },
          "family_id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "status": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "married",
                  "civil",
                  "religious",
                  "partnership",
                  "engaged",
                  "separated",
                  "annulled",
                  "divorced"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "The couple's relationship status as recorded; null when none is."
          }
        },
        "required": [
          "person_id",
          "family_id",
          "status"
        ]
      }
    },
    "children": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "person_id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "family_id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "pedigree": {
            "description": "GEDCOM pedigree of the child link (ADOPTED, FOSTER, SEALING, OTHER, or BIRTH); null = biological.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "person_id",
          "family_id",
          "pedigree"
        ]
      }
    }
  },
  "required": [
    "parents",
    "partners",
    "children"
  ]
}

get/workspaces/{workspace_id}/people/{person_id}/tree

Get tree data from a person

People, families (unions) and the edges between them, walked from the person. Data only, no layout.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
person_id	path	yes	The person id.
direction	query	no	ancestors, descendants or both (default both).
depth	query	no	Generations to walk, 1 to 8 (default 4).
parents	query	no	For a person with more than one set of parents, which family to climb: comma-separated person_id.family_id pairs. Malformed pairs are ignored.

Responses

200 The tree data. (PersonTree)
401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
403 The account has no paid plan. (ErrorResponse)
404 The workspace does not exist or is not visible to this key's owner. Also: The person does not exist or is not visible. (ErrorResponse)
422 Invalid direction or depth. (ErrorResponse)
429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)

200 response schema

{
  "type": "object",
  "properties": {
    "root_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "nodes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "person_id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "name": {
            "type": "string"
          },
          "sex": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "M",
                  "F",
                  "X",
                  "U"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "birth_year": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "death_year": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "person_id",
          "name",
          "sex",
          "birth_year",
          "death_year"
        ]
      }
    },
    "unions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "family_id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "partner_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            },
            "description": "Partners of this family that are in the tree."
          }
        },
        "required": [
          "family_id",
          "partner_ids"
        ]
      }
    },
    "edges": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "from": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "to": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "type": {
            "type": "string",
            "enum": [
              "partner",
              "child"
            ],
            "description": "partner: from a person to a family (union) they head. child: from a family to its child."
          }
        },
        "required": [
          "from",
          "to",
          "type"
        ]
      }
    },
    "truncated": {
      "type": "boolean",
      "description": "True when depth cut off relatives that exist beyond it."
    }
  },
  "required": [
    "root_id",
    "nodes",
    "unions",
    "edges",
    "truncated"
  ]
}

get/workspaces/{workspace_id}/people/{person_id}/expected-records

List records a person should have

Open research targets (for example a census the person should appear in), highest priority first.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
person_id	path	yes	The person id.
limit	query	no	Page size. Default 25, max 100.
cursor	query	no	The next_cursor of the previous page. Opaque.

Responses

200 A page of expected records. (ExpectedRecordList)
401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
403 The account has no paid plan. (ErrorResponse)
404 The workspace does not exist or is not visible to this key's owner. Also: The person does not exist or is not visible. (ErrorResponse)
422 Invalid limit or cursor. (ErrorResponse)
429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)

200 response schema

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "person_id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "kind": {
            "type": "string",
            "description": "census, military or vital."
          },
          "record_type": {
            "type": "string"
          },
          "jurisdiction": {
            "type": "string"
          },
          "sub_jurisdiction": {
            "type": [
              "string",
              "null"
            ]
          },
          "year_from": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "year_to": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "label": {
            "type": "string"
          },
          "detail": {
            "type": [
              "string",
              "null"
            ]
          },
          "demoted": {
            "type": "boolean"
          },
          "priority": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Higher first."
          }
        },
        "required": [
          "id",
          "person_id",
          "kind",
          "record_type",
          "jurisdiction",
          "sub_jurisdiction",
          "year_from",
          "year_to",
          "label",
          "detail",
          "demoted",
          "priority"
        ]
      }
    },
    "next_cursor": {
      "description": "Pass as ?cursor to get the next page. Null on the last page.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "data",
    "next_cursor"
  ]
}

post/workspaces/{workspace_id}/people/{person_id}/relatives

Add a relative

Link the person to a partner, parent, child, sibling or associate: an existing person (person_id) or a new one created in the same request (new_person). Same rules as the app, including the plan's person limit. Matching is queued, never run inline. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
person_id	path	yes	The person id.
Idempotency-Key	header	no	Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Request body (application/json, required)

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "partner",
        "parent",
        "child",
        "sibling",
        "associate"
      ],
      "description": "The relative's role relative to the path person: partner, parent, child, sibling or associate."
    },
    "person_id": {
      "description": "An existing person in this workspace. Exactly one of person_id and new_person.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "new_person": {
      "type": "object",
      "properties": {
        "given_name": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 200
            },
            {
              "type": "null"
            }
          ]
        },
        "surname": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 200
            },
            {
              "type": "null"
            }
          ]
        },
        "maiden_name": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 200
            },
            {
              "type": "null"
            }
          ]
        },
        "nickname": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 200
            },
            {
              "type": "null"
            }
          ]
        },
        "gender": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "M",
                "F",
                "X",
                "U"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "birth_date": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 100
            },
            {
              "type": "null"
            }
          ]
        },
        "birth_place": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 300
            },
            {
              "type": "null"
            }
          ]
        },
        "death_date": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 100
            },
            {
              "type": "null"
            }
          ]
        },
        "death_place": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 300
            },
            {
              "type": "null"
            }
          ]
        },
        "occupation": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 300
            },
            {
              "type": "null"
            }
          ]
        },
        "religion": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 200
            },
            {
              "type": "null"
            }
          ]
        },
        "notes": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 10000
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "additionalProperties": false
    },
    "family_id": {
      "description": "partner: fill the empty partner slot of this family instead of creating a new one. parent: the family to join (modes join, replace-join, add-as-coparent).",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "mode": {
      "description": "parent only. join, replace-join and add-as-coparent need family_id. Default create-bridge (adds an Unknown co-parent; counts against the person limit); new-single adds the parent alone.",
      "type": "string",
      "enum": [
        "join",
        "new-single",
        "create-bridge",
        "replace-join",
        "replace-bridge",
        "add-as-coparent"
      ]
    },
    "status": {
      "description": "partner only: the couple's relationship status.",
      "type": "string",
      "enum": [
        "married",
        "civil",
        "religious",
        "partnership",
        "engaged",
        "separated",
        "annulled",
        "divorced"
      ]
    },
    "pedigree": {
      "description": "parent only: how the path person is the parent's child.",
      "type": "string",
      "enum": [
        "birth",
        "adopted",
        "foster",
        "other"
      ]
    },
    "role": {
      "description": "associate only (required): the GEDCOM association role, e.g. WITN, GODP, FRIEND, OTHER.",
      "type": "string",
      "enum": [
        "CHIL",
        "CLERGY",
        "FATH",
        "FRIEND",
        "GODP",
        "HUSB",
        "MOTH",
        "MULTIPLE",
        "NGHBR",
        "OFFICIATOR",
        "PARENT",
        "SPOU",
        "WIFE",
        "WITN",
        "OTHER"
      ]
    },
    "role_phrase": {
      "description": "associate only: required when role is OTHER.",
      "type": "string",
      "maxLength": 200
    },
    "replace": {
      "description": "Change an existing link to person_id in place: the new link is added, then this one removed (one request).",
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "partner",
            "parent",
            "child",
            "associate"
          ]
        },
        "role": {
          "description": "Required when replacing an associate link: the role to replace.",
          "type": "string",
          "enum": [
            "CHIL",
            "CLERGY",
            "FATH",
            "FRIEND",
            "GODP",
            "HUSB",
            "MOTH",
            "MULTIPLE",
            "NGHBR",
            "OFFICIATOR",
            "PARENT",
            "SPOU",
            "WIFE",
            "WITN",
            "OTHER"
          ]
        }
      },
      "required": [
        "type"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "type"
  ],
  "additionalProperties": false
}

Responses

200 Linked to an existing person. (RelativeAdded)
201 A new person was created and linked. (RelativeAdded)
401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
403 The account has no paid plan, or the key is read-only (a read_write key is required). Also: the plan's person limit is reached (details: limit, used, plan). (ErrorResponse)
404 The workspace does not exist or is not visible to this key's owner. Also: A person or the family does not exist or is not visible. (ErrorResponse)
409 The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. Also: The family's partner or parent slot is already taken. (ErrorResponse)
422 Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid body, a field sent for the wrong type, a person linked to themselves, or a link the family rules refuse. (ErrorResponse)
429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)

200 response schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "person_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The relative: the person_id sent, or the id of the person created from new_person."
    }
  },
  "required": [
    "ok",
    "person_id"
  ]
}

201 response schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "person_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The relative: the person_id sent, or the id of the person created from new_person."
    }
  },
  "required": [
    "ok",
    "person_id"
  ]
}

delete/workspaces/{workspace_id}/people/{person_id}/relatives

Remove a relationship

The people are not deleted. Removing a link that does not exist changes nothing. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
person_id	path	yes	The person id.
Idempotency-Key	header	no	Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Request body (application/json, required)

{
  "type": "object",
  "properties": {
    "person_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "type": {
      "type": "string",
      "enum": [
        "partner",
        "parent",
        "child",
        "sibling",
        "associate"
      ]
    }
  },
  "required": [
    "person_id",
    "type"
  ],
  "additionalProperties": false
}

Responses

200 Removed. (Ok)
401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
403 The account has no paid plan, or the key is read-only (a read_write key is required). (ErrorResponse)
404 The workspace does not exist or is not visible to this key's owner. Also: A person does not exist or is not visible. (ErrorResponse)
409 The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. (ErrorResponse)
422 Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid body, or the same person twice. (ErrorResponse)
429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)

200 response schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ]
}

post/workspaces/{workspace_id}/people/{person_id}/unmerge

Undo a merge

The path person must be the merge's survivor. A group merge is undone as a whole. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
person_id	path	yes	The person id.
Idempotency-Key	header	no	Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Request body (application/json, required)

{
  "type": "object",
  "properties": {
    "match_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The merged match: match_id from a merge, an accepted match, or a group merge."
    }
  },
  "required": [
    "match_id"
  ],
  "additionalProperties": false
}

Responses

200 Unmerged. (UnmergeResult)
401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
403 The account has no paid plan, or the key is read-only (a read_write key is required). (ErrorResponse)
404 The workspace does not exist or is not visible to this key's owner. Also: The match does not exist, is not visible, or the person is not its survivor. (ErrorResponse)
409 The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. Also: The match is not a merge (nothing to unmerge). (ErrorResponse)
422 Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. (ErrorResponse)
429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)

200 response schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "restored_person_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      },
      "description": "Everyone the unmerge brought back: the whole group for a group merge, otherwise the merge's two people."
    }
  },
  "required": [
    "ok",
    "restored_person_ids"
  ]
}

patch/workspaces/{workspace_id}/expected-records/{expected_record_id}

Dismiss an expected record

{ dismissed: true } is the only change allowed. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
expected_record_id	path	yes	The expected record id.
Idempotency-Key	header	no	Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Request body (application/json, required)

{
  "type": "object",
  "properties": {
    "dismissed": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "dismissed"
  ],
  "additionalProperties": false
}

Responses

200 Dismissed. (Ok)
401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
403 The account has no paid plan, or the key is read-only (a read_write key is required). (ErrorResponse)
404 The workspace does not exist or is not visible to this key's owner. Also: The expected record does not exist or is not visible. (ErrorResponse)
409 The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. (ErrorResponse)
422 Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. (ErrorResponse)
429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)

200 response schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ]
}