---
title: "Create Relationship"
method: POST
path: "/tree/relationships"
tags: ["Relationships"]
---

# Create Relationship

`POST /tree/relationships`

## Request

- Base URL: `https://apibeta.familysearch.org/platform`
- URL: `https://apibeta.familysearch.org/platform/tree/relationships`
- Auth: HTTP bearer

Create a couple relationship or parent and child relationships.

## Headers

- `Content-Type` 'application/x-gedcomx-v1+json' | 'application/x-gedcomx-v1+xml' | 'application/x-fs-v1+json' | 'application/x-fs-v1+xml', required
- `X-Reason` string

## Request body

- union: Gedcomx object containing either a couple relationship or a child-and-parents relationship (or both). At least one relationship must be provided.
  - object
    - `relationships` object[], required: Array of couple relationships to create. Each relationship connects two spouses. See <a href="https://developers.familysearch.org/main/docs/json-schema#relationship" target="_blank">Relationship Schema (JSON)</a>
      - `type` string, required: The type of the relationship
      - `person1` object, required: The first person in the couple relationship (typically male for FamilySearch Family Tree)
        - `resource` string, required: The resource URI for the person. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
        - `resourceId` string, required: The person ID. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
      - `person2` object, required: The second person in the couple relationship (typically female for FamilySearch Family Tree)
        - `resource` string, required: The resource URI for the person. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
        - `resourceId` string, required: The person ID. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
      - `facts` object[]: Array of facts about the couple relationship (e.g., marriage facts)
        - `type` string, required: The type of the fact
        - `date` object: The date of the fact
          - `original` string: The original date string
        - `place` object: The place of the fact
          - `original` string: The original place string
        - `attribution` object: Attribution information for the fact
          - `changeMessage` string: The reason for the change
    - `childAndParentsRelationships` union[]: Array of child-and-parents relationships to create. Each relationship connects a child to up to two parents. See <a href="https://developers.familysearch.org/main/docs/json-schema#childandparentsrelationship" target="_blank">ChildAndParentsRelationship Schema (JSON)</a>
      - union
        - object
          - `parent1` object, required: The first parent in the relationship
            - `resource` string, required: The resource URI for the parent person. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
            - `resourceId` string, required: The person ID. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
          - `parent2` object: The second parent in the relationship
            - `resource` string, required: The resource URI for the parent person. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
            - `resourceId` string, required: The person ID. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
          - `child` object, required: The child in the relationship (required)
            - `resource` string, required: The resource URI for the child person. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
            - `resourceId` string, required: The person ID. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
          - `parent1Facts` object[]: Array of facts about the relationship between parent1 and the child
            - `type` string, required: The type of the parent-child relationship fact
            - `attribution` object: Attribution information for the fact
              - …
          - `parent2Facts` object[]: Array of facts about the relationship between parent2 and the child
            - `type` string, required: The type of the parent-child relationship fact
            - `attribution` object: Attribution information for the fact
              - …
        - object
          - `parent1` object: The first parent in the relationship
            - `resource` string, required: The resource URI for the parent person. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
            - `resourceId` string, required: The person ID. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
          - `parent2` object, required: The second parent in the relationship
            - `resource` string, required: The resource URI for the parent person. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
            - `resourceId` string, required: The person ID. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
          - `child` object, required: The child in the relationship (required)
            - `resource` string, required: The resource URI for the child person. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
            - `resourceId` string, required: The person ID. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
          - `parent1Facts` object[]: Array of facts about the relationship between parent1 and the child
            - `type` string, required: The type of the parent-child relationship fact
            - `attribution` object: Attribution information for the fact
              - …
          - `parent2Facts` object[]: Array of facts about the relationship between parent2 and the child
            - `type` string, required: The type of the parent-child relationship fact
            - `attribution` object: Attribution information for the fact
              - …
  - object
    - `relationships` object[]: Array of couple relationships to create. Each relationship connects two spouses. See <a href="https://developers.familysearch.org/main/docs/json-schema#relationship" target="_blank">Relationship Schema (JSON)</a>
      - `type` string, required: The type of the relationship
      - `person1` object, required: The first person in the couple relationship (typically male for FamilySearch Family Tree)
        - `resource` string, required: The resource URI for the person. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
        - `resourceId` string, required: The person ID. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
      - `person2` object, required: The second person in the couple relationship (typically female for FamilySearch Family Tree)
        - `resource` string, required: The resource URI for the person. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
        - `resourceId` string, required: The person ID. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
      - `facts` object[]: Array of facts about the couple relationship (e.g., marriage facts)
        - `type` string, required: The type of the fact
        - `date` object: The date of the fact
          - `original` string: The original date string
        - `place` object: The place of the fact
          - `original` string: The original place string
        - `attribution` object: Attribution information for the fact
          - `changeMessage` string: The reason for the change
    - `childAndParentsRelationships` union[], required: Array of child-and-parents relationships to create. Each relationship connects a child to up to two parents. See <a href="https://developers.familysearch.org/main/docs/json-schema#childandparentsrelationship" target="_blank">ChildAndParentsRelationship Schema (JSON)</a>
      - union
        - object
          - `parent1` object, required: The first parent in the relationship
            - `resource` string, required: The resource URI for the parent person. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
            - `resourceId` string, required: The person ID. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
          - `parent2` object: The second parent in the relationship
            - `resource` string, required: The resource URI for the parent person. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
            - `resourceId` string, required: The person ID. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
          - `child` object, required: The child in the relationship (required)
            - `resource` string, required: The resource URI for the child person. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
            - `resourceId` string, required: The person ID. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
          - `parent1Facts` object[]: Array of facts about the relationship between parent1 and the child
            - `type` string, required: The type of the parent-child relationship fact
            - `attribution` object: Attribution information for the fact
              - …
          - `parent2Facts` object[]: Array of facts about the relationship between parent2 and the child
            - `type` string, required: The type of the parent-child relationship fact
            - `attribution` object: Attribution information for the fact
              - …
        - object
          - `parent1` object: The first parent in the relationship
            - `resource` string, required: The resource URI for the parent person. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
            - `resourceId` string, required: The person ID. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
          - `parent2` object, required: The second parent in the relationship
            - `resource` string, required: The resource URI for the parent person. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
            - `resourceId` string, required: The person ID. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
          - `child` object, required: The child in the relationship (required)
            - `resource` string, required: The resource URI for the child person. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
            - `resourceId` string, required: The person ID. Can be a person from the main FamilySearch tree or from a user tree. To find an example person ID, see <a href="/reference/searchtreepersons" target="_blank">Search Tree Persons</a>.
          - `parent1Facts` object[]: Array of facts about the relationship between parent1 and the child
            - `type` string, required: The type of the parent-child relationship fact
            - `attribution` object: Attribution information for the fact
              - …
          - `parent2Facts` object[]: Array of facts about the relationship between parent2 and the child
            - `type` string, required: The type of the parent-child relationship fact
            - `attribution` object: Attribution information for the fact
              - …

## Response `201`

The creation of the relationship was successful. Expect a Location header specifying the link to the created relationship.

## Other responses

- `429`: The request was throttled.

---

[API](https://skmtc.dev/familysearch/apis/family-tree-endpoints.md) - [All operations](https://skmtc.dev/familysearch/apis/family-tree-endpoints/llms.txt) - [OpenAPI document](https://skmtc.dev/familysearch/apis/family-tree-endpoints/revisions/e248abd029e6?raw)