GanjoorRelatedPerson

suggest an addition, change or removal of a kinship edge - any logged-in user, same as suggesting a person edit. Goes into the pending queue; does not change anything. (Auth)

Changed on Oct 13, 2026

post/api/people/relationeditsuggestion

Request

Base URL
https://api.ganjoor.net (the document declares no server; this is the origin it was published from)
Auth
API key in header Authorization

Request body

idinteger

suggestion id

action0 | 1 | 2 | 3 | 4

what a GanjoorPersonRelationEditSuggestion proposes doing to the kinship graph

kind0 | 1

which kind of edge a GanjoorPersonRelationEditSuggestion is about: a kinship tie (GanjoorPersonRelation, via SuggestedRelationType/ExistingRelationId) or a non-family affiliation tie (GanjoorPersonAffiliation, via SuggestedAffiliationType/ExistingAffiliationId). Defaults to Family (0), so every suggestion row created before this field existed keeps being read exactly as it was before - a plain kinship suggestion.

existingRelationIdinteger nullable

for Modify/Remove when Kind is Family: the existing GanjoorPersonRelation row this suggestion targets. Null for Add, where there's nothing existing yet, and for any Kind == Affiliation suggestion (see ExistingAffiliationId instead).

existingAffiliationIdinteger nullable

for Modify/Remove when Kind is Affiliation: the existing GanjoorPersonAffiliation row this suggestion targets. Null for Add, and for any Kind == Family suggestion (see ExistingRelationId instead).

person1Idinteger

the pair this suggestion is about. For Add, this and Person2Id define the new relation. For Modify/Remove, these are copied from ExistingRelation at submission time, so the suggestion always accurately reflects what it targets even if the underlying relation changes again before this is reviewed.

person2Idinteger

second person id, see Person1Id

suggestedRelationType0 | 1 | 2 | 3

the kind of kinship edge a GanjoorPersonRelation represents between two GanjoorRelatedPerson rows. The graph is not a strict tree - siblings can be known without their parents, an ancestor can be known without the exact number of generations in between, etc. - so this is a small, deliberately open set rather than a rigid parent/child-only model.

confirmedExtraParentboolean

only meaningful when SuggestedRelationType is Parent. Normally, a third Parent edge for the same child is rejected (familytree.js's buildLayout only ever attaches the first two it sorts to the front and silently drops the rest). Set this to true only when a third recorded parent is genuinely intended (e.g. competing genealogy traditions for the same legendary figure) to add/keep it anyway.

reverseDirectionboolean

only meaningful for a Modify of a directional edge (Parent/Ancestor kinship, or any non-symmetric affiliation type): when true, approving the suggestion swaps the existing edge's Person1Id/Person2Id (e.g. fixes a Killer edge recorded the wrong way round) instead of the submitter having to delete it and add a new one. Person1Id/Person2Id of this suggestion itself stay those of the existing edge at submission time.

suggestedAffiliationType0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 99

the kind of non-family tie a GanjoorPersonAffiliation represents between two people - e.g. a minister serving a king, an advisor, a patron. Unlike PersonRelationType this has nothing to do with kinship; it's what lets two otherwise unrelated family trees show up as adjacent (e.g. "some Barmakids served the Abbasid court") without merging them into one tree. New values can be appended safely later (stored as int) as more cases come up.

suggestedDegreeHintinteger nullable

see GanjoorPersonRelation.DegreeHint - same for/Add/Modify/Remove-display purpose as SuggestedRelationType above

suggestedNotestring nullable

see GanjoorPersonRelation.Note - same Add/Modify/Remove-display purpose as SuggestedRelationType above

evidencePoemIdinteger nullable

evidence couplet (see GanjoorPersonRelationEvidence): the poem it is in. Required for Action == AddEvidence; optional for Action == Add (the evidence is attached to the new relation when the suggestion is approved). Ignored otherwise.

evidenceCoupletIndexinteger nullable

evidence couplet index inside EvidencePoemId's poem

evidenceCoupletTextstring nullable

snapshot of the evidence couplet's text, filled in by the server at submission time so the moderator sees exactly what the suggester pointed at

existingEvidenceIdinteger nullable

for Action == RemoveEvidence: the GanjoorPersonRelationEvidence row to detach (a plain id, not an FK, so deleting that row never conflicts with old suggestions that mention it)

suggestionNotestring nullable

suggester's note to the moderator (e.g. why an existing relation is wrong)

datestring date-time

date

userIdstring uuid

suggester's user id

reviewedboolean

reviewed

result0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18

correction review result

reviewDatestring date-time

review date

reviewNotestring nullable

review note

reviewerUserIdstring uuid nullable

reviewer's user id

Example request

{
  "user": {
    "rImage": {
      "folderName": "2017-08",
      "storedFileName": "85007253-09f2-4434-8b7e-1a23db2cd9c9.png"
    }
  },
  "reviewerUser": {
    "rImage": {
      "folderName": "2017-08",
      "storedFileName": "85007253-09f2-4434-8b7e-1a23db2cd9c9.png"
    }
  }
}

Response