diff --git a/docs/source/specs/openapi.yml b/docs/source/specs/openapi.yml
index 0f938efc34..c2a63e66aa 100644
--- a/docs/source/specs/openapi.yml
+++ b/docs/source/specs/openapi.yml
@@ -19,13 +19,160 @@ paths:
               schema:
                 $ref: "#/components/schemas/Status"
         '500':
-          description: unexpected error
+          description: Unexpected Error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/v1/customers/:
+    post:
+      summary: Create a customer
+      operationId: createCustomer
+      tags:
+        - Customer
+      requestBody:
+        description: Customer to add to the service
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CustomerIn'
+      responses:
+        '201':
+          description: An object describing the customer
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CustomerOut"
+        '500':
+          description: Unexpected Error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+    get:
+      summary: List the customers
+      operationId: listCustomers
+      tags:
+        - Customer
+      responses:
+        '200':
+          description: A paginated list of customer objects
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CustomerPagination"
+        '500':
+          description: Unexpected Error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/v1/customers/{id}/:
+    get:
+      summary: Get a customer
+      operationId: getCustomer
+      tags:
+        - Customer
+      parameters:
+        - name: id
+          in: path
+          description: ID of customer to get
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: A customer objects
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CustomerOut"
+
+        '404':
+          description: Not Found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        '500':
+          description: Unexpected Error
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
 components:
   schemas:
+    Customer:
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          example: "My Tech Company"
+    CustomerIn:
+      allOf:
+        - $ref: "#/components/schemas/Customer"
+        - required:
+          - owner
+      properties:
+        owner:
+          $ref: "#/components/schemas/UserIn"
+    CustomerPagination:
+      allOf:
+        - $ref: "#/components/schemas/ListPagination"
+        - required:
+          - results
+      properties:
+        results:
+          type: array
+          items:
+              $ref: "#/components/schemas/CustomerOut"
+    CustomerOut:
+      allOf:
+        - $ref: "#/components/schemas/Customer"
+        - required:
+          - id
+          - owner
+          - date_created
+      properties:
+        id:
+          type: string
+          format: uuid
+          example: "600562e7-d7d7-4516-8522-410e72792daf"
+        owner:
+          $ref: "#/components/schemas/UserOut"
+        date_created:
+          type: string
+          format: date-time
+    Error:
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: integer
+          format: int32
+        message:
+          type: string
+    ListPagination:
+      required:
+        - previous
+        - next
+      properties:
+        count:
+          type: integer
+          format: int64
+          example: 30
+        previous:
+          type: string
+          format: uri
+          example: "/api/v1/(resources)/?page=2"
+        next:
+          type: string
+          format: uri
+          example: "/api/v1/(resources)/?page=4"
     Status:
       required:
         - api_version
@@ -72,13 +219,35 @@ components:
         server_id:
           type: string
           example: "ff4eb8e4-ddfb-4b66-8e0e-045a244990f3"
-    Error:
+    User:
       required:
-        - code
-        - message
+        - username
+        - email
       properties:
-        code:
-          type: integer
-          format: int32
-        message:
+        username:
+          type: string
+          example: "smithj"
+        email:
+          type: string
+          format: email
+          example: "smithj@mytechco.com"
+    UserIn:
+      allOf:
+        - $ref: "#/components/schemas/User"
+        - required:
+          - password
+      properties:
+        password:
+          type: string
+          format: uuid
+          example: "str0ng!P@ss"
+    UserOut:
+      allOf:
+        - $ref: "#/components/schemas/User"
+        - required:
+          - id
+      properties:
+        id:
           type: string
+          format: uuid
+          example: "57e60f90-8c0c-4bd1-87a0-2143759aae1c"