diff --git a/docs/input-pills.md b/docs/input-pills.md
index c5f29ebb9c..be6ff06b63 100644
--- a/docs/input-pills.md
+++ b/docs/input-pills.md
@@ -60,3 +60,50 @@ $("#input_container + button").click(function () {
     console.log(pc.keys(), pc.values());
 });
 ```
+
+## `onPillCreate` method
+
+The `onPillCreate` method can have a few different key actions. The function can
+work as a validator, where if the `reject` function is called, it will disable
+the pill from being added to the list. You can provide a validator function and
+call `reject` if the pill isn't valid.
+
+The return type for your callback function should be what you want the key to be
+(this is not the displayed value, but rather than important ID of the pill). An
+example of a key vs. a value would be in the case of users. The value
+(human readable) would be the name of the user. We could show their name in the
+pill, but the key would represent their user ID. One could run a function like:
+
+```js
+pc.onPillCreate(function (value, reject) {
+    var id = users.getIDByFullName(value);
+
+    // user does not exist.
+    if (typeof id === "undefined") {
+        reject();
+    }
+
+    // return the user ID to be the key for retrieval later.
+    return id;
+});
+```
+
+However sometimes, we want to modify the visible text on pill submission, which
+requires changing the value and setting the key. We can use the "object" return
+type in the `onPillCreate` method to return a new key and value.
+
+This could be useful in the case where a user enters a valid user email to send
+to, but we want the pill to display their full name, and the key to be the user ID.
+
+```js
+pc.onPillCreate(function (value, reject) {
+    var user = users.getByEmail(value);
+
+    // user does not exist.
+    if (typeof id === "undefined") {
+        reject();
+    }
+
+    return { key: user.id, value: user.full_name };
+});
+```