The Grade.us API Version 4.0 is currently in Beta and is subject to change.

Open API Schema

Grade.us API (V4)

This JSON is structured to comply with the OpenAPI specification and can be imported into any number of API editors, including Swagger Editor.

Download | Swagger

{
  "openapi": "3.0.2",
  "info": {
    "title": "Grade.us API (V4)",
    "description": "This is the API for accessing resources on Grade.us.",
    "termsOfService": "https://www.grade.us/home/tos",
    "contact": {
      "name": "Carson Cole",
      "email": "carson@grade.us"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "4.0.0"
  },
  "servers": [
    {
      "url": "https://grade.us/api/v4",
      "description": "Production server for the Grade.us Version 4.0 API."
    }
  ],
  "paths": {
    "/users/": {
      "post": {
        "description": "This endpoint creates a User. Newly created Users will receive an email asking them to confirm their account and set their password unless send_system_emails is set to \"false\".",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "email",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": "The User's email address, which must be unique within Grade.us. This email is used to login to the Grade.us application."
          },
          {
            "in": "path",
            "name": "password",
            "required": false,
            "schema": {
              "type": "string"
            },
            "descripton": "The password for the User, used when logging into the Grade.us application.  If this attribute is not provided, user access can be obtained through the Grade.us application by utilizing the login links for \"Forgot your password?\"."
          },
          {
            "in": "path",
            "name": "first_name",
            "required": false,
            "schema": {
              "type": "string"
            },
            "descripton": "The first name of the User."
          },
          {
            "in": "path",
            "name": "last_name",
            "required": false,
            "schema": {
              "type": "string"
            },
            "descripton": "The last name of the User."
          },
          {
            "in": "path",
            "name": "permissions",
            "required": false,
            "schema": {
              "type": "string"
            },
            "descripton": "Permission dictate overall access to the Grade.us application.\r\n\r\nValues can include \"admin\" (all access), \"staff\" (all access except billing), \"client\" (access to certain profiles), or \"independent\" (access through a set brand).The permission \"owner\" will be on the master account, which can not be created by the API."
          },
          {
            "in": "path",
            "name": "send_system_emails",
            "required": false,
            "schema": {
              "type": "string"
            },
            "descripton": "Boolean value controlling whether system-generated emails, such as registration emails and other notifications, are sent to the User. If this value is true (default), a system-generated invitation email will be sent to the User to confirm their account. If this value is set to false, a user account does not go through the confirmation process and is immediately available for use. However, the user will need to retrieve their password by following the \"Forgot password\" process to obtain a password. "
          },
          {
            "in": "path",
            "name": "profiles",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": "An array of profiles User can access."
          }
        ]
      }
    },
    "/users/{user_uuid}": {
      "patch": {
        "description": "Updates a sub-User of a Master User. It is not possible to update or delete a Master User via the API.",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "user_uuid",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": "The UUID of a User."
          },
          {
            "in": "path",
            "name": "last_name",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": "The last name of the User."
          }
        ]
      },
      "get": {
        "description": "Get a specific user that belongs to logged in master user or master user",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "user_uuid",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": "The unique UUID of a User."
          }
        ]
      },
      "delete": {
        "description": "Delete a sub-User. It is not possible to delete a Master User.",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "user_uuid",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": "The unique User UUID."
          }
        ]
      }
    },
    "/users": {
      "get": {
        "description": "Get a collection of all users that belongs to a master user.",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [

        ]
      }
    },
    "/profiles/{profile_id}/delete_email": {
      "delete": {
        "description": "Delete email on Profile",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "profile_id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": "The ID of the Profile."
          }
        ]
      }
    },
    "/profiles/{profile_id}/create_email": {
      "post": {
        "description": "Create ability to send Emails.",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "profile_id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": ""
          }
        ]
      }
    },
    "/profiles/{profile_id}/delete_phone": {
      "delete": {
        "description": "This deletes the phone number.",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "profile_id",
            "required": false,
            "schema": {
              "type": "string"
            },
            "descripton": ""
          }
        ]
      }
    },
    "/profiles/{profile_id}/create_phone": {
      "post": {
        "description": "Create a phone number for SMS sending",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "profile_id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": ""
          },
          {
            "in": "path",
            "name": "country",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": "Allowed values are 'US', 'CA', 'AU', or 'GB'."
          }
        ]
      }
    },
    "/profiles/{profile_id}": {
      "patch": {
        "description": "This updates a Profile.",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "notes",
            "required": false,
            "schema": {
              "type": "string"
            },
            "descripton": null
          },
          {
            "in": "path",
            "name": "profile_id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": "The UUID of a Profile"
          },
          {
            "in": "path",
            "name": "custom_field_1",
            "required": false,
            "schema": {
              "type": "string"
            },
            "descripton": "An optional string field that can be used for Tag or other labels."
          }
        ]
      },
      "delete": {
        "description": "Delete a Profile.",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "profile_id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": "The UUID of a Profile."
          }
        ]
      },
      "get": {
        "description": "This returns a specific Profile.",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "profile_id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": "The UUID of a Profile."
          }
        ]
      }
    },
    "/profiles/": {
      "post": {
        "description": "This endpoint creates a Profile. Certain attributes of a new Profile will be populated by standard defaults, but these attributes can also be sourced from a default profile that can be created manually in the Grade.us application.",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": "The name or title of a Profile."
          }
        ]
      },
      "get": {
        "description": "This returns all Profiles.",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [

        ]
      }
    },
    "/profiles/{profile_id}/links/{link_id}": {
      "delete": {
        "description": "Delete a Link.",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "link_id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": ""
          },
          {
            "in": "path",
            "name": "profile_id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": ""
          }
        ]
      },
      "get": {
        "description": "Get a Link.",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "profile_id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": ""
          },
          {
            "in": "path",
            "name": "link_id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": ""
          }
        ]
      }
    },
    "/profiles/{profile_id}/links": {
      "post": {
        "description": "Create a Link.",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "profile_id",
            "required": false,
            "schema": {
              "type": "string"
            },
            "descripton": null
          },
          {
            "in": "path",
            "name": "url",
            "required": false,
            "schema": {
              "type": "string"
            },
            "descripton": null
          }
        ]
      },
      "get": {
        "description": "Get all Links.",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "profile_id",
            "required": false,
            "schema": {
              "type": "string"
            },
            "descripton": null
          }
        ]
      }
    },
    "/{profile_id}/links/{link_id}": {
      "patch": {
        "description": "Update a link.",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "profile_id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": ""
          }
        ]
      }
    },
    "/profiles/{profile_id}/reviews/": {
      "get": {
        "description": "Get all Reviews.",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "profile_id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": ""
          }
        ]
      }
    },
    "/profiles/{profile_id}/recipients": {
      "post": {
        "description": "Create one or more Recipients. Prior to creating a Recipient, phone and/or email service must be enabled.",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "profile_id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": ""
          },
          {
            "in": "path",
            "name": "email_address",
            "required": false,
            "schema": {
              "type": "string"
            },
            "descripton": "The email address of the Recipient, if an email campaign is desired."
          }
        ]
      },
      "get": {
        "description": "Get all Recipients.",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "profile_id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": ""
          }
        ]
      }
    },
    "/profiles/{profile_id}/recipients/{recipient_id}": {
      "get": {
        "description": "Get a Recipient.",
        "responses": {
          "200": {
            "description": "some description"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "profile_id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": ""
          },
          {
            "in": "path",
            "name": "recipient_id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "descripton": ""
          }
        ]
      }
    }
  },
  "security": [
    {
      "api_key": [

      ]
    }
  ],
  "components": {
    "securitySchemes": {
      "api_key": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header"
      }
    }
  },
  "externalDocs": {
    "url": "https://api.grade.us"
  }
}