taken in all content from the word document

documentation/src/content/docs/index.mdx

@@ -21,7 +21,7 @@ import { Card, CardGrid } from '@astrojs/starlight/components';
 	<Card title="Get an overview" icon="rocket">
 		[Get an overview](reference/01-background/) and start browsing how to authorize API-calls and browse the request & response specification.
 	</Card>
-	<Card title="Jump into the Endpoint specification" icon="puzzle">
-		[Visit the endpoint's description](reference/04-endpoint/).
+	<Card title="Check out the Endpoint specification" icon="puzzle">
+		[Visit the endpoint's description](reference/04-endpoint/) and understand how to form an import request.
 	</Card>
 </CardGrid>

documentation/src/content/docs/reference/04 endpoint.mdx

@@ -1,17 +1,19 @@
 ---
-title: Endpoint
+title: Endpoint description
 description: How to reach the endpoint and basic settings around the HTTP Headers
 ---
-import { Card, LinkCard } from '@astrojs/starlight/components';
+import { CardGrid, LinkCard } from '@astrojs/starlight/components';
 
 :::note
 <h4>The API URL of the import is</h4>
 <h5>https://connect.aheadintranet.com/api/PeopleImport</h5>
 :::
 
-It accepts **PUT**s With the following headers.
+## Request
 
-## x-functions-key
+The API accepts **PUT**s with the following headers.
+
+### x-functions-key
 
 The API-Key necessary to authorize the request
 
@@ -20,14 +22,11 @@ The API-Key necessary to authorize the request
   href="../03-authentication-authorization/"
 />
 
-## Content-Type
-
-Supported are
+### Content-Type
 
-* multipart/form-data
-* application/json
+Supported content types are
 
-### multipart/form-data
+#### multipart/form-data
 
 :::tip
 The structure of a multipart/form-data request is formally described at https://www.rfc-editor.org/rfc/rfc2388. It forms the basis of e.g., file uploads from HTML form submissions.
@@ -38,12 +37,63 @@ Each part of a multipart request also defines its own content-type. Currently su
 * application/json - An update of a profile in the form of a **Person update JSON object**.
 * application/pdf - A *.pdf document for upload to the personal section of a user
 
+A request may contain up to 50 parts. Each part corresponds to the update of one person or the addition of a file for a person.
+
+<CardGrid>
+    <LinkCard
+        title="Person update JSON object"
+        description="Learn about the specifics of the person update JSON"
+        href="../05-person-json-object/"
+    />
+    <LinkCard
+        title="Sending files"
+        description="Learn how to transmit files to your user's personal sections"
+        href="../06-sending-files/"
+    />
+</CardGrid>
+
+#### application/json
+
+Send a JSON array of **person update JSON objects**. The array may only contain up to **50 objects**.
+
+:::tip
+This kind of API usage only supports the update of fields directly related to profiles. It will **not** allow the upload of files.
+In this case, you will need to send `multipart/form-data`-requests
+:::
+
 <LinkCard
-  title="Person update JSON object"
-  description="Learn about the specifics of the person update JSON"
-  href="../05-person-json-object/"
+    title="Person update JSON object"
+    description="Learn about the specifics of the person update JSON"
+    href="../05-person-json-object/"
 />
 
-### application/json
+## Response
+
+:::caution
+Imports will be accepted on an employee-by-employee basis. That means that when the API returns the `422` error code, some of the sent employees may have been successfully imported. In such cases, you will need to identify the proper logs that are correlated with the GUID provided in the body of the response through ahead’s “Integrations” section in the management pages.
+:::
+
+### Status Code 200 
+
+The complete request has been processed without issues. The body of the response will contain a GUID with which this import call can be identified in the import logs (which will be accessible through ahead’s admin interface).
+
+### Status Code 400 
+
+If there’s any issue with the request at a basic level (e.g. wrong content type), a status code of `400` (Bad request) will be returned. Another possible reason is when all parts of the request failed to be processed.
+
+### Status Code 403 
+
+A request without API-Key or an unknown API-Key will cause a return of `403`. Such calls will not appear in the protocol.
+
+### Status Code 413
+
+A request contains more than 50 people updates.
+
+### Status Code 422
+
+If there are issues with the data itself, which may only apply to a part of the sent data, a status code of `422` (unprocessable content) will be returned. The body of the response will contain a GUID with which this import call can be identified such that it can be analyzed which specific import command went wrong.
 
-Send a JSON array of **person update JSON objects**.
+Typical conditions that would lead to a 422 response are:
+•	A particular JSON object could not be correlated with an existing entry (missing / wrong employeeId field)
+•	A JSON object contains fields that are not known as defined in the People Profile Definition
+•	A field is known, but contains the wrong kind of data

documentation/src/content/docs/reference/05 person-json-object.mdx

@@ -3,4 +3,49 @@ title: The person update JSON object
 description: Learn about the JSON object that updates a single person in the ahead people store
 ---
 
-TOOD
+A person update JSON object may appear as
+
+* part with content-type: application/json in a multipart 
+* as element of a JSON array within the body of a request whose content-type is application/json.
+
+Each JSON object must contain one of 
+•	the **“employeeId”** field. This field needs to correlate with a person’s “employeeId” value as stored in MS Entra.
+•	the **“userPrincipalName”** (UPN). This field needs to correlate with a person’s user principal name in MS Entra.
+
+Given that the following field has been defined in the people profile definition:
+
+```json
+{
+    "name": "birthDate",
+    "fieldType": "Date",
+    "source": "Api"
+}
+```
+
+Then the following update JSON would update the user with the UPN `joe@company.com` and add (_or update_) its birthday field.
+
+```json
+{
+    "userPrincipalName": "joe@company.com",
+    "birthDay": "1985-10-03",
+}
+```
+
+Sending a null for a supported field effectively deletes the value
+
+```json
+{
+    "userPrincipalName": "joe@company.com",
+    "birthDay": null,
+}
+```
+
+In other words, the update object may contain values for all or a subset of the fields that are marked with source = API 
+in the people profile definition.
+
+Provided that ahead is successful in correlating the person via one of the correlation fields, the provided values will be 
+merged with the existing values. In short, the following rules apply:
+
+*	Any fields not referenced will be left untouched.
+*	Provided fields will overwrite any previously existing values.
+*	If the API call sends “null” for a field, ahead will take this value and use it to overwrite / reset that specific value.

documentation/src/content/docs/reference/06 sending-files.mdx

@@ -0,0 +1,40 @@
+---
+title: Sending files through the import API
+description: Learn how to send files to ahead
+tableOfContents: false
+---
+
+In order to send a file to ahead, a field needs to be specified in the people profile definition to accept a certain kind of file.
+
+```json
+{
+    "name": "salary",
+    "fieldType": "File",
+    "source": "Api",
+    "isList": true
+}
+```
+
+In this example, files of type **salary** can be sent to ahead. The filename of the file(s) being sent via a 
+`multipart/form-data` request needs to follow a certain structure:
+
+```text
+{userIdentifier}__{fieldName}__{fileName}.pdf
+```
+
+Note the **<u>2</u>** underscores between the pieces of information. Following the example, 
+the following would be a valid file name:
+
+```text
+joe@company.com__salary__March 2023.pdf
+```
+
+It would upload a new file named **March 2023.pdf** under the **salary** category for the user with the UPN joe@company.com
+
+You can send up to **50 files** per multipart request.
+
+:::danger
+Regardless of whether you send 50 files on a request or, please note that the 
+total size of the request should **not** exceed **104 Megabytes**. 
+The request will not be processed if it exceeds that size.
+:::