Introduction

This API is a service that provides access to data relevant to the tuition repayment and other financial benefits provided by Tuition.io. The Tuition.io API conforms to the JSONAPI 1.0 specification. Please refer to the specification for additional details.

Authentication

Access to resources in the Tuition.io API requires a valid API Key and an authentication token.

Tuition.io expects your unique, public API key to be included in the x-api-key request header:

x-api-key: <API_KEY>

To authenticate requests, the Tuition.io API expects an authentication token to be sent in the tio-auth-token request header:

tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw

Build Your Own Token

# Using the Ruby JWT Gem: [https://github.com/jwt/ruby-jwt]

claims = {
  iat: 1609883853, # required
  exp: 1609887476, # required
  id: '14', # optional
  iss: 'Example Company, LLC' # optional
}

token = JWT.encode(claims, 'purrrrrfectt', 'HS512')

#!/usr/bin/env bash
jwt_header=$(echo -n '{"alg":"HS512"}' | base64 | sed s/\+/-/g | sed 's/\//_/g' | sed -E s/=+$//)
payload=$(echo -n '{"iat":1609883853,"exp":1609887476,"iss":"Example Company, LLC","id":"14"}' | base64 | sed s/\+/-/g |sed 's/\//_/g' |  sed -E s/=+$//)
secret='purrrrrfectt'
hmac_signature=$(echo -n "${jwt_header}.${payload}" |  openssl sha512 -hmac "$secret" -binary | base64 | sed s/\+/-/g | sed 's/\//_/g' | sed -E s/=+$//)
jwt="${jwt_header}.${payload}.${hmac_signature}"

echo ${jwt}

The authentication token is a JWT encoded with the HS512 algorithm and "signed" with the "secret" component of your API Key.

For example, Tuition.io provides you with the following API Key details:

Attribute Name	Value
`key`	`meowmeowmeow`
`secret`	`purrrrrfectt`

You might build your own authentication token with the code shown here.

JWT encoding libraries are available for most languages. Learn more at jwt.io.

Supported JWT Claims

Currently, the only required JWT claims are the "issued at" and "expiration" time stamps: iat and exp.

Parameter	Required	Description
`iat`	YES	The time the JWT was computed in seconds since epoch. The Tuition.io API does not allow JWTs older than 1 year of age or issued in the future. Setting `iat` to the current timestamp should work in most cases.
`exp`	YES	The time the JWT will expire. The Tuition.io API will reject requests with expired JWTs. For security, we recommend JWTs that expire after a few minutes. But the API allows JWTs up to 1 year old.
`id`	no	ID of authenticated user. If omitted, API Key user will be used.
`iss`	no	Something to identify you as the issuer of the token.

Request Headers Example

curl -X GET "https://localhost:3030/employees" \
    -H "x-api-key: meowmeowmeow" \
    -H "tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw"

Authentication Errors

The Tuition.io API will report the following errors when there is a problem with the provided API Key or authentication token.

Problem	Status	Message	Description
Invalid Signature	403	"Invalid JWT token. Make sure algorithm and JWT secret match."	The authentication token does not appear to be "signed" with the correct API Key secret.
Issued At (`iat`) Invalid	403	'The token does not have a valid "issued at" time.'	The token's `iat` timestamp is missing, more than 1 year in the past, or set in the future.
Expired Token	401	"The token has expired."	The token's `exp` timestamp is missing or has passed.
Wrong Encoding Algorithm	403	"Invalid JWT token. Make sure algorithm and JWT secret match."	The token should be encoded with `HS512`. Other encoding strategies will fail.
Missing Token	400	"Missing Authentication Token"	The `tio-auth-token` was not set in the request headers.
Missing / Invalid API Key	400	"Invalid API Key"	The `x-api-key` header was not sent or contains an invalid / inactive value.

JSONAPI Basics

The Tuition.io API conforms to the JSONAPI 1.0 specification.

Query Parameters

Parameter	Default	Description
page[limit]	50	The number of records to fetch. (Max: 200)
page[offset]	0	The index of the first record to fetch.
include	NONE	A comma-separated list of association types to "side-load" in the response payload.
sort	id	For listing endpoints, the attribute the API should use to sort results. Prefix with a `-` to indicate descending order.
fields[type]	all	A comma-separated list of attributes to render in the JSON response
filter[type]	NONE	A comma-separated list of attribute values with which to filter the results.

Companies

List Companies

## Request Companies
curl "https://localhost:3030/companies" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw'

{
  "data": [
    {
      "id": "1337",
      "type": "companies",
      "attributes": {
        "name": "Cat Co."
      }
    }
  ],
  "meta": {
    "page": {
      "total": 1
    },
    "requester": 14,
    "copyright": "©2021"
  }
}

HTTP Request

GET https://localhost:3030/companies

Attributes

Attribute	Description
`name`	The name of the company.

Associations

Association	One / Many	Description
`employees`	Many	List of employees associated to the company
`plans`	Many	List of contribution plans associated to the company
`user`	One	The User record that represents this Company/Organization

Show Company

## Request Company
curl "https://localhost:3030/companies/1337" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw'

{
  "data": {
    "id": "1337",
    "type": "companies",
    "attributes": {
      "name": "Cat Co."
    }
  },
  "meta": {
    "requester": 14,
    "copyright": "©2021"
  }
}

HTTP Request

GET https://localhost:3030/companies/<ID>

URL Parameters

Parameter	Description
ID	The ID of the company to retrieve

Attributes

Attribute	Description
`name`	The name of the company.

Associations

Association	One / Many	Description
`employees`	Many	List of employees associated to the company
`plans`	Many	List of contribution plans associated to the company
`user`	One	The User record that represents this Company/Organization

Employees

Get Employees

curl "https://localhost:3030/employees?page%5Blimit%5D=2" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw'

{
  "data":
    [{
      "id":"4064",
      "type":"employees",
      "attributes": {
        "first-name": "Anna",
        "last-name":"Riley",
        "email": "anna@test.com"
      }
    }, {
      "id":"4065",
      "type":"employees",
      "attributes": {
        "first-name":"Loren",
        "last-name":"Jefferson",
        "email": "loren@test.com"
      }
    }]
  },
  "meta": {
    "page": {
      "total": 140
    }
  }
}

GET https://localhost:3030/employees?page%5Blimit%5D=2

Query Parameters

GET https://localhost:3030/employees?filter[is-active]=false

Parameter	Default	Description
`filter[is-active]`	true	Filter employees by `is-active`

Get a Specific Employee

curl "https://localhost:3030/employees/<ID>" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw'

{
  "data": {
    "id": "4064",
    "type":"employees",
    "attributes": {
      "payroll-id": "123ABC",
      "is-active": true,
      "status": "CREATED",
      "first-name": "Calvin",
      "last-name": "Broadus",
      "suffix": "Jr.",
      "email": "snoop.dogg@example.com",
      "phone-number": "123-456-7890",
      "address-line-1": "123 Main St",
      "address-line-2": "Apt 5",
      "city": "Long Beach",
      "state": "CA",
      "postal-code": "90814",
      "country": "United States",
      "birth-year": "1971",
      "employment-type": "FULL_TIME",
      "employment-start-date": "2020-01-13T00:00:00.000Z",
      "employment-end-date": null,
      "salary": 50000000,
      "rate-period": "YEARLY",
      "contribution-amount": 15000,
      "eligibility-start-date": "2020-01-13T00:00:00.000Z",
      "eligibility-end-date": null,
      "title": "Celebrity Host",
      "department": "Martha & Snoop's Potluck Dinner Party",
      "cost-center": "ABC123",
      "custom-attributes": {
        "favorite-hobby": "cooking"
      }
    }
  }
}

This endpoint retrieves a specific employee.

HTTP Request

GET https://localhost:3030/employees/<ID>

URL Parameters

Parameter	Description
ID	The ID of the employee to retrieve

Attributes

Attribute	Type	Description
`payroll-id`	string	The unique payroll ID of the employee
`is-active`	boolean	If the employee is active (defaults to `true`) (read-only)
`status`	string	Participation status (Valid values are `CREATED`, `INVITED`, `PARTICIPATING`, `LEAVE_OF_ABSENCE`, `DEACTIVATED`, or `REACTIVATED`) (read-only)
`first-name`	string	First / given name (e.g. "Calvin")
`last-name`	string	Last / family name (e.g. "Broadus")
`suffix`	string	Name suffix (e.g. "Jr.")
`email`	string	Email address (e.g. "snoop.dogg@example.com")
`phone-number`	string	Phone number (e.g. "123-456-7890")
`address-line-1`	string	Street address (e.g. "123 Main St")
`address-line-2`	string	Additional street address (e.g. "Apt 5")
`city`	string	City (e.g. "Long Beach")
`state`	string	State (e.g. "CA")
`postal-code`	string	Postal code (e.g. "90814")
`country`	string	Country (e.g. "United States")
`birth-year`	string	Birth year (e.g. "1973")
`employment-type`	string	Employment type. Valid values are `FULL_TIME`, `PART_TIME`, or `EXEMPT`.
`employment-start-date`	string	Employment start date, in ISO 8601 format
`employment-end-date`	string	Employment end date, in ISO 8601 format
`salary`	integer	Salary / pay rate (in the smallest whole unit of currency, i.e. cents for USD)
`rate-period`	string	Pay rate period of the employee as it relates to the value of `salary`. Valid values are `YEARLY`, `MONTHLY`, `WEEKLY`, `BI-WEEKLY` or `HOURLY`.
`contribution-amount`	integer	Contribution amount (in the smallest whole unit of currency, i.e. cents for USD)
`eligibility-start-date`	string	Eligibility start date, in ISO 8601 format
`eligibility-end-date`	string	Eligibility end date, in ISO 8601 format
`title`	string	Title (e.g. "Executive Director")
`department`	string	Department (e.g. "Human Resources")
`cost-center`	string	Cost center
`custom-attributes`	object	An object for storing any custom attributes relevant to the employee

Associations

Association	One / Many	Description
`company`	One	The company associated with the employee
`plan`	One	The contribution plan associated with the employee

Create Employee

curl -X "POST" "https://localhost:3030/employees" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw' \
     -H 'Content-Type: application/vnd.api+json' \
     -d $'{
        "data": {
          "type": "employees",
          "attributes": {
            "first-name": "Cory",
            "last-name": "Loken",
            "payroll-id": "32191",
            "email": "cory@test.com",
            "phone-number": "999-999-1212"
          },
          "relationships": {
            "company": {
              "data": {
                "type": "companies",
                "id": "<COMPANY_ID>"
              }
            }
          }
        }
      }'

{
  "data": {
    "id":"3",
    "type":"employees",
    "attributes": {
      "first-name": "Cory",
      "last-name": "Loken",
      "email": "cory@test.com",
      "payroll-id": "32191",
      "phone-number": "999-999-1212"
    }
  }
}

This endpoint creates a specific employee.

HTTP Request

POST https://localhost:3030/employees

BODY Parameters

Parameter	Description
COMPANY_ID	The COMPANY_ID of the employee to create
first-name	The first name of the employee
last-name	The last name of the employee
email	The email address where the plan invite is sent
payroll-id	The company payroll id for the employee

Update a Specific Employee

curl -X PUT "https://localhost:3030/employees/<ID>" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw' \
     -d $'{
        "data": {
          "id": "4064",
          "type": "employees",
          "attributes": {
            "first-name": "Anna Changed"
          }
        }
      }'

{
  "data": {
    "id": "4064",
    "type":"employees",
    "attributes": {
      "first-name": "Anna Changed",
      "last-name": "Riley",
      "email": "anna@test.com",
      "phone-number": "999-555-1111"
    }
  }
}

This endpoint updates a specific employee.

HTTP Request

PUT https://localhost:3030/employees/<ID>

URL Parameters

Parameter	Description
ID	The ID of the employee to update

BODY Parameters

Parameter	Description
first-name	The first name of the employee
last-name	The last name of the employee
email	The email address where the plan invite is sent
phone-number	The phone number of the employee

Terminate a Specific Employee

curl -X DELETE "https://localhost:3030/employees/<ID>" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw' \

This endpoint terminates a specific employee.

Employees who have been terminated will be inactive and have status DEACTIVATED.

HTTP Request

DELETE https://localhost:3030/employees/<ID>

URL Parameters

Parameter	Description
ID	The ID of the employee to terminate

Reinstate a Specific Employee

curl -X PATCH "https://localhost:3030/employees/<ID>/reinstate" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw' \

This endpoint reinstates a previously terminated employee.

Employees who have been reinstated will be active and have status REACTIVATED.

HTTP Request

PATCH https://localhost:3030/employees/<ID>/reinstate

URL Parameters

Parameter	Description
ID	The ID of the employee to reinstate

Invite a Specific Employee

curl -X PATCH "https://localhost:3030/employees/<ID>/invite" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw' \

This endpoint sends an invite to an eligible employee.

HTTP Request

PATCH https://localhost:3030/employees/<ID>/invite

URL Parameters

Parameter	Description
ID	The ID of the employee to invite

Add / Update a Plan for an Employee

curl -X "POST" "https://localhost:3030/plans/2/relationships/employees" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw' \
     -H 'Content-Type: application/vnd.api+json' \
     -d $'{
        "data": [
          { "type": "employees", "id": <EMPLOYEE_ID> }
        ]
      }'

This endpoint attaches a contribution plan to a specific employee.

HTTP Request

POST https://localhost:3030/employees/<PLAN_ID>/relationships/employees

URL Parameters

Parameter	Description
PLAN_ID	The PLAN_ID to attach to employee

BODY Parameters

Parameter	Description
EMPLOYEE_ID	The EMPLOYEE_ID to receiving the contribution

Remove a Plan from an Employee

curl -X "DELETE" "https://localhost:3030/plans/2/relationships/employees" \
     -H 'x-api-key: localAPIKey' \
     -H 'tio-auth-token: 123...' \
     -H 'Content-Type: application/vnd.api+json' \
     -d $'{
        "data": [
          { "type": "employees", "id": "3" }
        ]
      }'

This endpoint removes a contribution plan from a specific employee.

HTTP Request

DELETE https://localhost:3030/employees/<PLAN_ID>/relationships/employees

URL Parameters

Parameter	Description
PLAN_ID	The PLAN_ID to attach to employee

BODY Parameters

Parameter	Description
EMPLOYEE_ID	The EMPLOYEE_ID to receiving the contribution

Workspaces

Get Workspaces

## Request Workspaces
curl "https://localhost:3030/workspaces?page%5Blimit%5D=2" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw'

{
  "data":
    [{
      "id": "9877",
      "type": "workspaces",
      "attributes": {
        "name": "Tio",
        "description": "This is the parent workspace for all other workspaces",
        "path":[9877],
        ...
      },
    }, {
      "id": "9878",
      "type": "workspaces",
      "attributes": {
        "name":"Purple Admin Workspace",
        "description":"This is the purple workspace",
        "path":[9877,9878],
        ...
      }
    }],
    "meta": {
      "page": {
        "total":2
      }
    }
  }

GET https://localhost:3030/workspaces?page%5Blimit%5D=2

Query Parameters

GET https://localhost:3030/workspaces?filter[is-active]=false

Parameter	Default	Description
`filter[is-active]`	true	Filter employees by `is-active`

Get a Specific Workspace

curl "https://localhost:3030/workspaces/<ID>" \\
     -H 'x-api-key: meowmeowmeow' \\
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw'

{
  "data": {
    "id": "9878",
    "type": "workspaces",
    "attributes": {
      "name": "Purple Admin Workspace",
      "description": "This is the purple workspace",
      "path": [9877,9878],
      ...
    }
  }
}

This endpoint retrieves a specific workspace.

HTTP Request

GET https://localhost:3030/workspaces/<ID>

URL Parameters

Parameter	Description
ID	The ID of the workspace to retrieve

Associations

Association	One / Many	Description
`employees`	Many	List of employees associated to the workspace
`users`	Many	The User records associated with the workspace

Request Workspace with Employees

This endpoint attaches a single employee to a specific workspace.

curl "https://localhost:3030/workspaces/<ID>?include=employees,users" </span>
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw'

HTTP Request

GET https://localhost:3030/workspaces/<ID>?include=employees,users

Create Workspace

## Create Workspace curl -X "POST" "https://localhost:3030/workspaces" \ -H 'x-api-key: meowmeowmeow' \ -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw' \ -H 'Content-Type: application/vnd.api+json' \ -d $'{ "data": { "type": "workspaces", "attributes": { "custom-attributes": { "agency-name": "PAW Workspace", "agent-name": "Phillip Fry" }, "name": "A Workspace", "description": "A workspace" }, "relationships": { "parent": { "data": { "type": "workspaces", "id": "9877" } } } } }'

{
  "data":
    {"id": "9876",
    "type": "workspaces",
    "attributes": {
      "name": "A Workspace",
      "description": "A workspace",
      "custom-attributes": {
        "agency-name": "PAW Workspace",
        "agent-name": "Cory Loken",
        "agent-license": "1234ABC"
      }
    }
  }
}

This endpoint creates a specific workspace.

HTTP Request

POST https://localhost:3030/workspaces

BODY Parameters

Parameter	Description
name	The name of the workspace
description	The description of the workspace
custom-attributes	A place to store arbitrary values associated with a workspace

Update a Specific Workspace

curl -X "PATCH" "https://localhost:3030/workspaces/9876" \ -H 'x-api-key: meowmeowmeow' \ -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw' \ -H 'Content-Type: application/vnd.api+json' \ -d $'{ "data": { "id": "9876", "type": "workspaces", "attributes": { "name": "Updated Name", "description": "Updated description for workspace" } } }'

{
  "data": {
    "id": "9876",
    "type": "workspaces",
    "attributes": {
      "name": "Updated Name",
      "description": "Updated description for workspace",
      "path": [9877,9876]
    }
  }
}

This endpoint updates a specific workspace.

HTTP Request

PUT https://localhost:3030/workspaces/<ID>

URL Parameters

Parameter	Description
ID	The ID of the workspace to update

BODY Parameters

Parameter	Description
name	The name of the workspace
description	The description of the workspace
custom-attributes	A place to store arbitrary values associated with a workspace

Attach Employees to Workspace

curl -X "POST" "http://https://localhost:3030/workspaces/<WORKSPACE_ID>/relationships/employees" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw' \
     -H 'Content-Type: application/vnd.api+json' \
     -d $'{
        "data": [{
          "id": "1",
          "type": "employees"
        }]
}'

This endpoint attaches a single employee to a specific workspace.

HTTP Request

POST https://localhost:3030/workspaces/<ID>/relationships/employees

Remove Employees from Workspace

curl -X "DELETE" "http://https://localhost:3030/workspaces/<WORKSPACE_ID>/relationships/employees" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw' \
     -H 'Content-Type: application/vnd.api+json' \
     -d $'{
        "data": [{
          "id": "1",
          "type": "employees"
        }]
      }'

This endpoint removes a single employee to a specific workspace.

Deactivate a Specific Workspace

curl -X "DELETE" "https://localhost:3030/workspaces/" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw' \

This endpoint deactivates a specific workspace.

HTTP Request

DELETE https://localhost:3030/workspaces/<ID>

URL Parameters

Parameter	Description
ID	The ID of the workspace to deactivate

Agents

Get Agents

curl "https://localhost:3030/agents?page%5Blimit%5D=2" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw'

{
  "data":
    [{
      "id":"4064",
      "type":"agents",
      "attributes": {
        "first-name": "Anna",
        "last-name":"Riley",
        "email": "anna@test.com"
      }
    }, {
      "id":"4065",
      "type":"agents",
      "attributes": {
        "first-name":"Loren",
        "last-name":"Jefferson",
        "email": "loren@test.com"
      }
    }]
  },
  "meta": {
    "page": {
      "total": 140
    }
  }
}

GET https://localhost:3030/agents?page%5Blimit%5D=2

Query Parameters

GET https://localhost:3030/agents?filter[is-active]=false

Parameter	Default	Description
`filter[is-active]`	true	Filter agents by `is-active`

Get a Specific Agent

curl "https://localhost:3030/agents/<ID>" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw'

{
  "data": {
    "id": "4064",
    "type":"agents",
    "attributes": {
      "first-name": "Calvin",
      "last-name": "Broadus",
      "email": "snoop.dogg@example.com"
    }
  }
}

This endpoint retrieves a specific agent.

HTTP Request

GET https://localhost:3030/agents/<ID>

URL Parameters

Parameter	Description
ID	The ID of the agent to retrieve

List Agents

curl "https://localhost:3030/agents" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw'

{
  "data": [{
    "id": "738306350509981713",
    "type": "agents",
    "attributes": {
      "email": "guohawo@crunchy.bananas",
      "first-name": "Antonio",
      "last-name":"Hunter"
    }
  }],
  "meta": {
    "page": { "total":1 }
  }
}

This endpoint retrieves a list agent. Use the ?include=workspaces to retrieve related workspaces.

HTTP Request

GET https://localhost:3030/agents

Create Agent

curl -X "POST" "https://localhost:3030/agents" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw' \
     -H 'Content-Type: application/vnd.api+json' \
     -d $'{
      "data":
      {
          "type": "agents",
          "attributes":
          {
              "first-name": "Cornelia",
              "last-name": "Gray",
              "email": "in@crunchy.bananas",
              "custom-attributes": {
                "agent-license": "1234ABC"
              }
          },
          "relationships":
          {
              "workspace":
              {
                  "data":
                  {
                      "type": "workspaces",
                      "id": "<WORKSPACE_ID>"
                  }
              }
          }
      }
  }'

{
  "data": {
    "id":"3",
    "type":"employees",
    "attributes": {
      "first-name": "Cornelia",
      "last-name": "Gray",
      "email": "in@crunchy.bananas",
      "custom-attributes": {
        "agent-license": "1234ABC"
      }
    }
  }
}

This endpoint creates a specific agent.

HTTP Request

POST https://localhost:3030/agents

BODY Parameters

Parameter	Description
WORKSPACE_ID	The WORKSPACE_ID that the agent is assigned
first-name	The first name of the agent
last-name	The last name of the agent
email	The email that will be used for authentication
custom-attributes	A place to store arbitrary values associated with an agent

Update a Specific Agent

curl -X PUT "https://localhost:3030/agents/<ID>" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw' \
     -d $'{
        "data": {
          "id": "4064",
          "type": "agents",
          "attributes": {
            "first-name": "Anna Changed"
          }
        }
      }'

{
  "data": {
    "id": "4064",
    "type":"agents",
    "attributes": {
      "first-name": "Anna Changed",
      "last-name": "Riley"
    }
  }
}

This endpoint updates a specific agent.

HTTP Request

PUT https://localhost:3030/employees/<ID>

URL Parameters

Parameter	Description
ID	The ID of the agent to update

BODY Parameters

Parameter	Description
first-name	The first name of the agent
last-name	The last name of the agent
email	The email that will be used for authentication
custom-attributes	A place to store arbitrary values associated with an agent

Add Agent Workspace(s)

curl -X "POST" "https://localhost:3030/agents/<ID>/relationships/workspaces" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw' \
     -H 'Content-Type: application/vnd.api+json' \
     -d $'{
      "data": [
        { "type": "workspaces", "id": "<WORKSPACE_ID>" },
        { "type": "workspaces", "id": "<WORKSPACE_ID>" },
        { "type": "workspaces", "id": "<WORKSPACE_ID>" }
      ]
    }'

This endpoint attaches an agent plan to a specific workspace.

HTTP Request

POST https://localhost:3030/agents/<ID>/relationships/workspaces

URL Parameters

Parameter	Description
ID	The ID of the agent to attach to workspace

BODY Parameters

Parameter	Description
WORKSPACE_ID	The WORKSPACE_ID to attach agent

Remove Agent Workspace(s)

curl -X "DELETE" "https://localhost:3030/agents/<ID>/relationships/workspaces" \
     -H 'x-api-key: meowmeowmeow' \
     -H 'tio-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MDk4ODM4NTMsImV4cCI6MTYwOTg4NzQ3NiwiaXNzIjoiRXhhbXBsZSBDb21wYW55LCBMTEMifQ.BcfVGaT_0up7wTgOhXDl49RTCQeydDnPt_r8XUJjADLxGXDoLCjuxwb5_fBb1EKQZPSz6TAwgYiOcfdXFLxglw' \
     -H 'Content-Type: application/vnd.api+json' \
     -d $'{
  "data": [
    { "type": "workspaces", "id": "<WORKSPACE_ID>" }
  ]
}'

This endpoint removes an agent plan to a specific workspace(s).

HTTP Request

POST https://localhost:3030/agents/<ID>/relationships/workspaces

URL Parameters

Parameter	Description
ID	The ID of the agent to attach to workspace

BODY Parameters

Parameter	Description
WORKSPACE_ID	The WORKSPACE_ID to attach agent

Errors

The Tuition.io API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The resource requested is not allowed by current api key.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- You tried to access a resource with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
422	Unprocessable Entity. More specific information in response payload.
429	Too Many Requests -- You're requesting too many resources! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.