Add high-level docs

doc/invite-flow.md

@@ -0,0 +1,29 @@
+# Invite flow
+
+To enable a better on-boarding experience we need a way to correlate users and their inviter. One way is to keep a list of invites of a user that stores a unique id (e.g. facebook id, or generate random identifier) which can be kept through until the invitee hits the signup. If the invitee signs up and the conenction to the inviter is preserved we can automatically create connections for those so they can hit the ground running.
+
+### API
+
+To create an invite from the current user the following endpoint should be called. The key and value are entirely up to the caller to decide, but must match one of the key/value pairs in the [`social_ids`](https://github.com/tapglue/snaas/wiki/the-user-object#social-ids) of the invitee during signup. Given the Facebook id of the invitee is known:
+
+```
+> POST /me/invites
+{
+	"facebook": "1234"
+}
+
+< 204 No Content
+```
+
+Then during singup the same information should be provvided for the user.
+
+```
+> POST /users?invite-connections=true
+{
+	...
+	"social_ids": {
+		"facebook": "1234"
+	}
+	...
+}
+```