> For the complete documentation index, see [llms.txt](https://docs.cootje.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cootje.com/cootje-api/klant-inlener/personen-toevoegen/urenverantwoordelijke.md).

# Urenverantwoordelijke

Een urenverantwoordelijke toevoegen aan een klant: velden, rechten en voorbeelden.

De urenverantwoordelijke keurt namens de klant de uren van de professional goed. Hiermee voeg je een urenverantwoordelijke toe aan de klant.

* **Vereist recht:** Personen kunnen bewerken

Bestaat de persoon nog niet in Cootje, gebruik dan de eerste aanroep. Staat de persoon er al in, bijvoorbeeld bij een ander bedrijf, gebruik dan de tweede.

## Nieuwe persoon toevoegen

* **Aanroep:** `POST /organizations/persons`

Je maakt de persoon aan en koppelt hem in dezelfde aanroep aan de klant waarvoor hij uren goedkeurt.

### Verplichte velden

| Veld                   | Soort | Toelichting                                                                        |
| ---------------------- | ----- | ---------------------------------------------------------------------------------- |
| `person.firstName`     | tekst | Voornaam                                                                           |
| `person.lastName`      | tekst | Achternaam                                                                         |
| `person.initials`      | tekst | Voorletters                                                                        |
| `person.email`         | tekst | Een geldig e-mailadres dat nog niet bij een andere persoon in de omgeving voorkomt |
| `membership.companyId` | tekst | Het `_id` van het bedrijf                                                          |
| `membership.roles`     | lijst | De rol van de persoon bij het bedrijf: `4` urenverantwoordelijke                   |

### Verplicht in bepaalde gevallen

| Situatie                                                  | Dan verplicht                                           |
| --------------------------------------------------------- | ------------------------------------------------------- |
| Je vult een deel van het adres in (`person.address`)      | `street`, `houseNumber`, `zipcode` en `city`, alle vier |
| De nationaliteit is Nederlands en je vult `person.bsn` in | Een geldig burgerservicenummer                          |

### Optionele velden

| Veld                     | Soort             | Toelichting                                                                                                                                                       |
| ------------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `membership.permissions` | lijst             | De rechten van de persoon bij het bedrijf, als getallen. Laat je dit weg, dan heeft de persoon de rol maar geen rechten. Zie de tabel hieronder                   |
| `person.tussenvoegsel`   | tekst             | Tussenvoegsel, zoals "van der"                                                                                                                                    |
| `person.gender`          | getal             | `1` man, `2` vrouw                                                                                                                                                |
| `person.phoneNumber`     | tekst             | Telefoonnummer                                                                                                                                                    |
| `person.address`         | object            | Adres: `street`, `houseNumber`, `houseNumberAddition`, `zipcode`, `city` en `country`                                                                             |
| `person.dateOfBirth`     | tekst             | Geboortedatum                                                                                                                                                     |
| `person.nationality`     | tekst             | Nationaliteit                                                                                                                                                     |
| `person.bsn`             | tekst             | Burgerservicenummer                                                                                                                                               |
| `person.maritalStatus`   | tekst             | Burgerlijke staat                                                                                                                                                 |
| `person.function`        | tekst             | Functie                                                                                                                                                           |
| `person.isApiAccount`    | ja/nee            | `true` voor een account dat alleen voor een koppeling is bedoeld. Standaard `false`                                                                               |
| `bankAccount`            | object            | Bankrekening van de persoon: `iban` (een geldig IBAN) en `type` (`1` gewone rekening, `2` G-rekening). Beide velden zijn verplicht als je dit onderdeel meestuurt |
| `acceptAddressWarnings`  | ja/nee, in de URL | `true` om de persoon ook op te slaan als het adres niet bevestigd kan worden                                                                                      |

Zonder `country` in het adres wordt het land `NL`.

### Rechten bij deze rol

Cootje kent de rechten niet vanzelf toe. Stuur ze mee in `membership.permissions`. Dit zijn de rechten die Cootje zelf bij deze rol gebruikt:

| Getal | Recht                                             |
| ----- | ------------------------------------------------- |
| `506` | Urenstaten inzien waaraan de persoon gekoppeld is |
| `503` | Contracten inzien waaraan de persoon gekoppeld is |

### Voorbeeld

```bash
curl -X POST "https://mijn.cootje.com/api/organizations/persons" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "person": {
      "firstName": "Tom",
      "lastName": "Visser",
      "initials": "T.",
      "email": "tom@voorbeeld.nl"
    },
    "membership": {
      "companyId": "0b7c2f6e-3d1a-4f5b-9a8e-1c2d3e4f5a6b",
      "roles": [
        4
      ],
      "permissions": [
        506,
        503
      ]
    }
  }'
```

### Wat je terugkrijgt

De aangemaakte persoon, met het nieuwe `_id`. De koppeling met het bedrijf staat niet in het antwoord:

```json
{
  "_id": "3d4e5f6a-7b8c-4d9e-8f0a-2b3c4d5e6f7a",
  "createdAt": 1799746200000,
  "firstName": "Tom",
  "tussenvoegsel": "",
  "lastName": "Visser",
  "initials": "T.",
  "gender": null,
  "email": "tom@voorbeeld.nl",
  "phoneNumber": "",
  "address": {
    "street": "",
    "houseNumber": "",
    "houseNumberAddition": "",
    "city": "",
    "zipcode": "",
    "country": "NL"
  },
  "bsn": "",
  "dateOfBirth": "",
  "nationality": "",
  "maritalStatus": "",
  "function": "",
  "isApiAccount": false,
  "displayName": "Tom Visser",
  "displayLastName": "Visser"
}
```

Klopt de invoer niet (`400`) of kan het adres niet bevestigd worden (`422`), dan is het antwoord een lijst met bevindingen en is de persoon niet opgeslagen:

```json
[
  {
    "propertyName": "FirstName",
    "errorMessage": "Voornaam is verplicht"
  }
]
```

## Bestaande persoon koppelen

* **Aanroep:** `POST /organizations/memberships/companies/{companyId}/persons/{personId}`

### Verplichte velden

| Veld        | Soort            | Toelichting                                                      |
| ----------- | ---------------- | ---------------------------------------------------------------- |
| `companyId` | tekst, in de URL | Het `_id` van het bedrijf                                        |
| `personId`  | tekst, in de URL | Het `_id` van de persoon                                         |
| `roles`     | lijst            | De rol van de persoon bij het bedrijf: `4` urenverantwoordelijke |

### Optionele velden

| Veld          | Soort | Toelichting                                                                                                                                    |
| ------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `permissions` | lijst | De rechten van de persoon bij het bedrijf, als getallen uit de tabel hierboven. Laat je dit weg, dan heeft de persoon de rol maar geen rechten |

### Voorbeeld

```bash
curl -X POST "https://mijn.cootje.com/api/organizations/memberships/companies/0b7c2f6e-3d1a-4f5b-9a8e-1c2d3e4f5a6b/persons/3d4e5f6a-7b8c-4d9e-8f0a-2b3c4d5e6f7a" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "roles": [
      4
    ],
    "permissions": [
      506,
      503
    ]
  }'
```

### Wat je terugkrijgt

De koppeling tussen de persoon en het bedrijf:

```json
{
  "_id": "4e5f6a7b-8c9d-4e0f-9a1b-3c4d5e6f7a8b",
  "companyId": "0b7c2f6e-3d1a-4f5b-9a8e-1c2d3e4f5a6b",
  "personId": "3d4e5f6a-7b8c-4d9e-8f0a-2b3c4d5e6f7a",
  "roles": [
    4
  ],
  "permissions": [
    506,
    503
  ]
}
```

Bestaat het bedrijf of de persoon niet, dan is het antwoord een lijst met fouten:

```json
[
  {
    "propertyName": "PersonId",
    "errorMessage": "Persoon bestaat niet"
  }
]
```

## Goed om te weten

* Het bedrijf moet al in Cootje staan. Zie [Klant registreren](https://docs.cootje.com/cootje-api/klant-inlener/klant-registreren.md).
* In een contract verwijs je naar deze persoon in het veld `timesheetApprovers`.
* Een contract heeft minstens één urenverantwoordelijke nodig, tenzij goedkeuring voor dat contract is uitgeschakeld.
* Voor een contract moet de persoon een naam en een e-mailadres hebben. Op dat adres krijgt hij het verzoek om uren goed te keuren.

## Antwoorden

| Code  | Betekenis                                                                                 |
| ----- | ----------------------------------------------------------------------------------------- |
| `200` | De aangemaakte persoon, of de koppeling                                                   |
| `400` | De invoer klopt niet. Het antwoord is de lijst met fouten                                 |
| `401` | Geen geldig token, of het account mist het recht                                          |
| `422` | Het adres van een nieuwe persoon kon niet bevestigd worden. De persoon is niet opgeslagen |
