> 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/uitnodigingen-onboarding/versturen.md).

# Versturen

Een uitnodiging aanmaken en versturen: verplichte en optionele velden en de tekst van de e-mail.

Hiermee maak je een uitnodiging aan en verstuur je de e-mail naar de ontvanger.

* **Aanroep:** `POST /organizations/invite/send`
* **Vereist recht:** Personen kunnen bewerken, of Alle vacatures bewerken

{% hint style="warning" %}
De API controleert de invoer van deze aanroep niet. Een uitnodiging zonder de velden hieronder wordt wel aangemaakt, maar werkt niet: de e-mail komt dan niet aan of bevat geen link.
{% endhint %}

## Verplichte velden

| Veld        | Soort | Toelichting                                                                                                                              |
| ----------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `email`     | tekst | Het e-mailadres van de ontvanger                                                                                                         |
| `type`      | getal | De soort uitnodiging: `1` zzp, `2` tijdelijke arbeidsovereenkomst, `3` inhuur bij een bestaand bedrijf, `4` inhuur met een nieuw bedrijf |
| `emailBody` | tekst | De tekst van de e-mail, als HTML. Zet de tekst `[LINK_VALUE]` op de plek waar de persoonlijke link moet komen                            |

## Verplicht in bepaalde gevallen

| Situatie                                        | Dan verplicht                                                                                                                                                          |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` is `3` (inhuur bij een bestaand bedrijf) | `companyId`: het `_id` van het bedrijf waaraan de persoon wordt gekoppeld. Zie [Bedrijf registreren](https://docs.cootje.com/cootje-api/inhuur/bedrijf-registreren.md) |
| `type` is `4` (inhuur met een nieuw bedrijf)    | `isCustomer` en/of `isSupplier` op `true`: of het nieuwe bedrijf klant, leverancier of beide wordt                                                                     |

## Optionele velden

| Veld                  | Soort  | Toelichting                                                                                                                                     |
| --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                | tekst  | De naam van de ontvanger. Wordt ingevuld op de plek van `[NAME]` in de e-mail                                                                   |
| `documentListId`      | tekst  | Het `_id` van de documentenlijst die bepaalt welke documenten de ontvanger aanlevert. De lijsten vraag je op met `GET /documents/documentlists` |
| `registerCredentials` | ja/nee | `true` als de ontvanger bij het invullen ook een eigen inlog aanmaakt. Standaard `false`                                                        |
| `vacancyRelationId`   | tekst  | Het `_id` van de sollicitatie waar deze uitnodiging bij hoort                                                                                   |
| `contractDetails`     | object | Gegevens waarmee Cootje meteen een conceptcontract klaarzet. Laat je dit onderdeel weg, dan komt er geen conceptcontract                        |

## Velden in `contractDetails`

Alle velden in dit onderdeel zijn optioneel.

| Veld                               | Soort  | Toelichting                                                                                                                                      |
| ---------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `hirerCompanyId`                   | tekst  | Het `_id` van de inlener, een bedrijf in Cootje                                                                                                  |
| `contactHirerPersonId`             | tekst  | Het `_id` van de contactpersoon bij de inlener                                                                                                   |
| `authorizedSignatoryHirerPersonId` | tekst  | Het `_id` van de tekenbevoegde bij de inlener                                                                                                    |
| `timesheetApproverPersonId`        | tekst  | Het `_id` van de urenverantwoordelijke                                                                                                           |
| `recruiterPersonId`                | tekst  | Het `_id` van de recruiter                                                                                                                       |
| `timesheetAttachmentRequired`      | ja/nee | `true` als een urenstaat verplicht is bij het indienen van uren                                                                                  |
| `hirerIsEndCustomer`               | ja/nee | `true` als de inlener ook de eindklant is                                                                                                        |
| `endCustomerName`                  | tekst  | De naam van de eindklant, als dat niet de inlener is                                                                                             |
| `role`                             | tekst  | De functie binnen de opdracht                                                                                                                    |
| `location`                         | tekst  | De plaats waar het werk wordt gedaan                                                                                                             |
| `description`                      | tekst  | De omschrijving van de werkzaamheden                                                                                                             |
| `expectedOutcome`                  | tekst  | Het beoogde resultaat                                                                                                                            |
| `hoursPerWeek`                     | getal  | Aantal uren per week. `-1` betekent "nader overeen te komen"                                                                                     |
| `startDate`, `endDate`             | getal  | Start- en einddatum, in milliseconden sinds 1970                                                                                                 |
| `remarks`                          | tekst  | Bijzonderheden                                                                                                                                   |
| `customerInvoiceEmail`             | tekst  | Het e-mailadres voor de factuur aan de klant                                                                                                     |
| `invoiceReferences`                | lijst  | Factuurreferenties. Per regel `invoiceReferenceId` en `value`                                                                                    |
| `financial`                        | object | De financiële afspraken van het contract, zoals tarieven en betaaltermijnen. Laat je dit weg, dan gelden de standaardwaarden van de contractvorm |

## De tekst van de e-mail

Cootje vult bij het versturen twee plekken in de tekst in:

| Tekst in `emailBody` | Wordt vervangen door                                                                                                |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `[LINK_VALUE]`       | De persoonlijke link van de ontvanger                                                                               |
| `[NAME]`             | De waarde van `name`. Is die leeg, dan de voornaam van een bestaande persoon met dit e-mailadres, en anders "Lezer" |

De standaardtekst van jullie omgeving haal je op met `GET /notifications/systemmessages/{type}`, met op de plek van `{type}` hetzelfde getal als de soort uitnodiging. Het veld `body` uit dat antwoord kun je meesturen als `emailBody`.

## Voorbeeld

```bash
curl -X POST "https://mijn.cootje.com/api/organizations/invite/send" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sanne@voorbeeld.nl",
    "name": "Sanne",
    "type": 1,
    "emailBody": "<p>Beste [NAME],</p><p>Lever je gegevens aan via <a href=\"[LINK_VALUE]\">deze link</a>.</p>",
    "documentListId": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
    "registerCredentials": true,
    "contractDetails": {
      "hirerCompanyId": "0b7c2f6e-3d1a-4f5b-9a8e-1c2d3e4f5a6b",
      "role": "Projectleider zorg",
      "hoursPerWeek": 32,
      "startDate": 1803859200000,
      "endDate": 1819670400000
    }
  }'
```

## Wat je terugkrijgt

De code uit de persoonlijke link, als tekst tussen aanhalingstekens:

```json
"a1b2c3d4"
```

Deze code is niet het `_id` van de uitnodiging. Het `_id` heb je nodig om de uitnodiging opnieuw te versturen of te verwijderen; je vindt het via [Ophalen](https://docs.cootje.com/cootje-api/uitnodigingen-onboarding/ophalen.md), waar je de uitnodiging herkent aan het veld `code`.

## Antwoorden

| Code  | Betekenis                                                          |
| ----- | ------------------------------------------------------------------ |
| `200` | De uitnodiging is aangemaakt en verstuurd. Het antwoord is de code |
| `401` | Geen geldig token, of het account mist het recht                   |
