Adds documentation about Group calls and relationship properties to the Userlist documentation

Author: benedikt

src/connections/destinations/catalog/userlist/index.md

@@ -2,52 +2,114 @@
 rewrite: true
 title: Userlist Destination
 ---
+
 [Userlist](https://userlist.com/?utm_source=segmentio&utm_medium=docs&utm_campaign=partners) allows you to send behavior-based messages to your SaaS users. It's great for onboarding users as well as nurturing them throughout their journey.
 
 This destination is maintained by Userlist. For any issues with the destination, [contact the Userlist Support team](mailto:[email protected]).
 
 {% include content/beta-note.md %}
 
-
 ## Getting Started
 
 {% include content/connection-modes.md %}
 
-1. From the Segment web app, click **Catalog**.
-2. Search for "Userlist" in the Catalog, select it, and choose which of your sources to connect the destination to.
-3. Enter the "Push API Key" into your Segment Settings UI which you can find from your [Userlist Push API settings](https://app.userlist.com/settings/push).
+1.  From the Segment web app, click **Catalog**.
+2.  Search for "Userlist" in the Catalog, select it, and choose which of your sources to connect the destination to.
+3.  Enter the "Push API Key" into your Segment Settings UI which you can find from your [Userlist Push API settings](https://app.userlist.com/settings/push).
 
-_**NOTE:** The Userlist Destination does not support tracking of anonymous users, so make sure to call `identify` before calling `track`. If you do call `track` on unidentified users, you will receive a 400 error which you can disregard if it was intentional._
+_**NOTE:** The Userlist Destination does not support tracking of anonymous users, so make sure to call `identify` before calling `track` or `group`. If you do call `track` or `group` on unidentified users, you will receive a 400 error which you can disregard if it was intentional._
 
 ## Identify
 
 If you're not familiar with the Segment Specs, take a look to understand what the [Identify method](https://segment.com/docs/connections/spec/identify/) does. An example call would look like:
 
-	analytics.identify('userId123', {
-	  email: '[email protected]',
-	  name: 'John Doe',
-	  role: 'Owner',
-	  createdAt: '2019-03-21T12:12:54.735+01:00'
-	});
+```javascript
+analytics.identify('userId123', {
+  email: '[email protected]',
+  name: 'John Doe',
+  role: 'Owner',
+  createdAt: '2019-03-21T12:12:54.735+01:00'
+});
+```
 
 Identify calls will be sent to Userlist as user records. If the `userId` is already known, it'll update the user record, otherwise it'll create a new one.
 
 Here's how Segment fields map to Userlist users:
 
-| Segment field | Userlist field | Description
-|-------------|---------------|-----------
-| `userId` | `identifier` | The unique identifier for this user. |
-| `traits` | `properties` | Additional properties describing the user. |
-| `traits.email` | `email` | The user's email address. |
-| `traits.createdAt` | `signed_up_at` | The time when the user was created. |
-
+| Segment field      | Userlist field | Description                                |
+| ------------------ | -------------- | ------------------------------------------ |
+| `userId`           | `identifier`   | The unique identifier for this user.       |
+| `traits`           | `properties`   | Additional properties describing the user. |
+| `traits.email`     | `email`        | The user's email address.                  |
+| `traits.createdAt` | `signed_up_at` | The time when the user was created.        |
 
 ## Track
 
 If you're not familiar with the Segment Specs, take a look to understand what the [Track method](https://segment.com/docs/connections/spec/track/) does. An example call would look like:
 
-	analytics.track('Project created', {
-	  projectName: 'Party Planning'
-	});
+```javascript
+analytics.track('Project created', {
+  projectName: 'Party Planning'
+});
+```
 
 Track calls will be sent to Userlist as a new event. You may send additional properties to describe the event in more detail. Both the event name and additional properties will be stored with the event and normalized to snake case (`project_created` and `project_name`) automatically within Userlist.
+
+To associate an event with both a user and a company, please include the company's identifier as `context.groupId` on the Track call:
+
+```javascript
+analytics.track(
+  'Project created',
+  {
+    projectName: 'Party Planning'
+  },
+  {
+    context: {
+      groupId: 'companyId123'
+    }
+  }
+);
+```
+
+## Group
+
+If you're not familiar with the Segment Specs, take a look to understand what the [Group method](https://segment.com/docs/connections/spec/group/) does. An example call would look like:
+
+```javascript
+analytics.group('companyId123', {
+  name: 'Segment'
+});
+```
+
+| Segment field      | Userlist field | Description                                |
+| ------------------ | -------------- | ------------------------------------------ |
+| `groupId`          | `identifier`   | The unique identifier for this company.    |
+| `traits`           | `properties`   | Additional properties describing the user. |
+| `traits.name`      | `name`         | The company's name.                        |
+| `traits.createdAt` | `signed_up_at` | The time when the user was created.        |
+
+Group calls will be sent to Userlist as company records. If the `groupId` is already known, it'll update the company record, otherwise it'll create a new one.
+
+Userlist supports custom properties to describe the relationship between users and groups (such as the user's role in a company). You can pass relationship properties in a Group call by using Userlist specific extensions.
+
+```javascript
+analytics.group(
+  'companyId123',
+  {
+    name: 'Segment'
+  },
+  {
+    integrations: {
+      Userlist: {
+        extensions: {
+          relationship: {
+            properties: {
+              role: 'owner'
+            }
+          }
+        }
+      }
+    }
+  }
+);
+```