From cdfff6787890124f393c8ca8f9f146482a63f53d Mon Sep 17 00:00:00 2001
From: Maxime Dor <max@kamax.io>
Date: Thu, 26 Oct 2017 03:04:43 +0200
Subject: [PATCH 1/3] Create spec for IS bulk lookup

---
 api/identity/lookup.yaml               | 55 +++++++++++++++++++++++++-
 specification/identity_service_api.rst |  1 +
 2 files changed, 55 insertions(+), 1 deletion(-)

diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml
index 18e5e77d8..4d5ab5b7d 100644
--- a/api/identity/lookup.yaml
+++ b/api/identity/lookup.yaml
@@ -82,4 +82,57 @@ paths:
                 description: The unix timestamp at which the association was verified.
               signatures:
                 type: object
-                description: The signatures of the verifying identity service which show that the association should be trusted, if you trust the verifying identity service.
+                description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.
+  "/bulk_lookup":
+    post:
+      summary: Lookup Matrix user IDs for a list of 3pid.
+      description: Lookup Matrix user IDs for a list of 3pid.
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: {
+              "threepids":
+              [
+                ["email","user@example.org"],
+                ["msisdn", "123456789"],
+                ["email","user2@example.org"]
+              ]
+            }
+            properties:
+              threepids:
+                type: array
+                items:
+                  type: array
+                  title: 3PID mappings
+                  items:
+                    type: string
+                    title: 3PID medium or address
+                description: an array of array containing the `3PID Medium type`_ in first position and the 3PID Address in second position.
+            required:
+              - "threepids"
+      responses:
+        200:
+          description: A list of known 3PID mappings for the supplied 3PIDs.
+          examples:
+            application/json: {
+              "threepids": [
+                ["email","user@example.org", "@bla:example.org"],
+                ["msisdn", "123456789", "@blah2:example.com"]
+              ]
+            }
+          schema:
+            type: object
+            properties:
+              threepids:
+                type: array
+                items:
+                  type: array
+                  title: 3PID mappings
+                  items:
+                    type: string
+                    title: 3PID medium or address or the Matrix ID
+                description: an array of array containing the `3PID Medium type`_ in first position, the 3PID Address in second position and Matrix ID is in third position.
+            required:
+              - "threepids"
diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst
index fa03e162c..85b9789f6 100644
--- a/specification/identity_service_api.rst
+++ b/specification/identity_service_api.rst
@@ -291,3 +291,4 @@ It will look up ``token`` which was stored in a call to ``store-invite``, and fe
  }
 
 .. _`Unpadded Base64`:  ../appendices.html#unpadded-base64
+.. _`3PID Types`:  ../appendices.html#pid-medium-types

From 836e6c81d1dc81b177e244b91af418d6aee2aa94 Mon Sep 17 00:00:00 2001
From: Maxime Dor <max@kamax.io>
Date: Thu, 26 Oct 2017 12:37:25 +0200
Subject: [PATCH 2/3] Fix spelling

---
 api/identity/lookup.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml
index 4d5ab5b7d..385e8a602 100644
--- a/api/identity/lookup.yaml
+++ b/api/identity/lookup.yaml
@@ -85,8 +85,8 @@ paths:
                 description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.
   "/bulk_lookup":
     post:
-      summary: Lookup Matrix user IDs for a list of 3pid.
-      description: Lookup Matrix user IDs for a list of 3pid.
+      summary: Lookup Matrix user IDs for a list of 3pids.
+      description: Lookup Matrix user IDs for a list of 3pids.
       parameters:
         - in: body
           name: body
@@ -109,7 +109,7 @@ paths:
                   items:
                     type: string
                     title: 3PID medium or address
-                description: an array of array containing the `3PID Medium type`_ in first position and the 3PID Address in second position.
+                description: an array of arrays containing the `3PID Medium type`_ in first position and the 3PID Address in second position.
             required:
               - "threepids"
       responses:

From 5147a3b975d258699831fbe49358274b68a8cba5 Mon Sep 17 00:00:00 2001
From: David Baker <dave@matrix.org>
Date: Tue, 14 Nov 2017 17:14:56 +0000
Subject: [PATCH 3/3] Fix broken links & grammar

---
 api/identity/lookup.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml
index 285844c0d..7cd7fdedd 100644
--- a/api/identity/lookup.yaml
+++ b/api/identity/lookup.yaml
@@ -111,7 +111,7 @@ paths:
                   items:
                     type: string
                     title: 3PID medium or address
-                description: an array of arrays containing the `3PID Medium type`_ in first position and the 3PID Address in second position.
+                description: an array of arrays containing the `3PID Types`_ with the ``medium`` in first position and the ``address`` in second position.
             required:
               - "threepids"
       responses:
@@ -135,6 +135,6 @@ paths:
                   items:
                     type: string
                     title: 3PID medium or address or the Matrix ID
-                description: an array of array containing the `3PID Medium type`_ in first position, the 3PID Address in second position and Matrix ID is in third position.
+                description: an array of array containing the `3PID Types`_ with the ``medium`` in first position, the ``address`` in second position and Matrix ID in third position.
             required:
               - "threepids"