# Add a relationship

`POST /api/v1/vaults/{vault}/contacts/{contact}/relationships`

Link a contact to somebody else in the same vault.

The other person is an existing contact named by other_contact, somebody new named by first_name, or, when you send neither, somebody whose name is unknown. Somebody new has no record of their own unless creates_record is true.

Linking somebody to themselves, using a type that is switched off, or making somebody their own ancestor answers 422, naming other_contact or relationship_type.

## Parameters

- `vault` (string, required): The vault both people live in, named either by the readable name it reports as slug or by its id.
- `contact` (string, required): One of the two people, named either by their slug or by their id. A contact addressed through the wrong vault answers 404.
- `relationship_type` (uuid, required): The id of a relationship type of your account. A type that is switched off answers 422.
- `other_contact` (string, optional): The other person, a contact of the same vault, named by their slug or their id. Not allowed with first_name or last_name.
- `first_name` (string, optional): The first name of somebody who has no record of their own. Up to 255 characters.
- `last_name` (string, optional): Their last name. Needs first_name.
- `creates_record` (boolean, optional): True to give that person a full record of their own in the vault.
- `holds_role_a` (boolean, optional): Whether the contact in the address holds role_a and the other person role_b. For a parent and child type, true says the contact is the parent. Ignored for a symmetric type. True when left out.

## Returns

The relationship object that was added.

- `data` (object): The relationship.
- `data.type` (string): Always relationship. It names the kind of record, so a caller holding several kinds can tell them apart without looking at where they came from.
- `data.id` (string): The id of this record, as a string even when it reads as a number. It is what every endpoint naming this record takes.
- `data.attributes` (object): Everything the record holds.
- `data.attributes.relationship_type` (object): What the link is.
- `data.attributes.relationship_type.id` (uuid): The id of the relationship type.
- `data.attributes.relationship_type.name` (string): The name of the relationship type.
- `data.attributes.relationship_type.is_symmetric` (boolean): True when both people hold the same role, as partners do.
- `data.attributes.contact_a` (object): The person holding role_a.
- `data.attributes.contact_a.id` (uuid): The id of the contact.
- `data.attributes.contact_a.slug` (string): The readable name of the contact, which addresses it as well as its id.
- `data.attributes.contact_a.name` (string): The name of the contact, as it is shown.
- `data.attributes.contact_a.is_partial` (boolean): True for somebody who exists only through a relationship and has no record of their own.
- `data.attributes.contact_a.role` (string): The role this person holds, which is the type's role_a.
- `data.attributes.contact_b` (object): The person holding role_b.
- `data.attributes.contact_b.id` (uuid): The id of the contact.
- `data.attributes.contact_b.slug` (string): The readable name of the contact, which addresses it as well as its id.
- `data.attributes.contact_b.name` (string): The name of the contact, as it is shown.
- `data.attributes.contact_b.is_partial` (boolean): True for somebody who exists only through a relationship and has no record of their own.
- `data.attributes.contact_b.role` (string): The role this person holds, which is the type's role_b.
- `data.attributes.status` (string): current or ended.
- `data.attributes.started_on` (string): When it started, written as a year, a month and a day, or null.
- `data.attributes.ended_on` (string): When it ended, or null. Always null while the relationship is current.
- `data.attributes.created_at` (timestamp): When the relationship was recorded, as a count of seconds since 1970.
- `data.attributes.updated_at` (timestamp): When it last changed, as a count of seconds. Equal to created_at until it first changes.
- `data.links` (object): Where to find this record.
- `data.links.self` (string): The absolute address this record is read from.

## Rate limit

Sixty requests per minute, per user, shared by every key and device. Every answer carries the budget left in `X-RateLimit-Remaining`.

## Request

```sh
curl https://my.monicahq.com/api/v1/vaults/dunder-mifflin/contacts/jim-halpert/relationships \
  -X POST \
  -H "Authorization: Bearer $MONICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "relationship_type": "b52f0d7e-1c84-4a39-9e6b-3f7a20c5d816",
      "other_contact": "pam-beesly",
      "first_name": "Cece",
      "last_name": "Halpert",
      "creates_record": "false",
      "holds_role_a": "true"
  }'
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/contacts/jim-halpert/relationships', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    relationship_type: 'b52f0d7e-1c84-4a39-9e6b-3f7a20c5d816',
    other_contact: 'pam-beesly',
    first_name: 'Cece',
    last_name: 'Halpert',
    creates_record: 'false',
    holds_role_a: 'true',
  }),
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->post('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/contacts/jim-halpert/relationships', [
    'relationship_type' => 'b52f0d7e-1c84-4a39-9e6b-3f7a20c5d816',
    'other_contact' => 'pam-beesly',
    'first_name' => 'Cece',
    'last_name' => 'Halpert',
    'creates_record' => 'false',
    'holds_role_a' => 'true',
]);
```

## Response

`201`

```json
{
    "data": {
        "type": "relationship",
        "id": "7c1e9a42-5b3d-4f60-a8e2-0d94b6c3f185",
        "attributes": {
            "relationship_type": {
                "id": "b52f0d7e-1c84-4a39-9e6b-3f7a20c5d816",
                "name": "Partner",
                "is_symmetric": true
            },
            "contact_a": {
                "id": "2d6b8f13-9a07-4c5e-b1f4-6e3a90d2c748",
                "slug": "jim-halpert",
                "name": "Jim Halpert",
                "is_partial": false,
                "role": "partner"
            },
            "contact_b": {
                "id": "e8a41c06-7f25-4b93-8d0e-52c9b7f1a364",
                "slug": "pam-beesly",
                "name": "Pam Beesly",
                "is_partial": false,
                "role": "partner"
            },
            "status": "current",
            "started_on": "2007-05-10",
            "ended_on": null,
            "created_at": 1790380800,
            "updated_at": 1790380800
        },
        "links": {
            "self": "https://my.monicahq.com/api/v1/vaults/dunder-mifflin/contacts/jim-halpert/relationships/7c1e9a42-5b3d-4f60-a8e2-0d94b6c3f185"
        }
    }
}
```
