NAV

Introduction

Sample GraphQL Request:

POST https://api.edvisor.io/graphql

Sample GraphQL Request Body:

{
  "query": "query {
    student(studentId: 123) {
      firstname, 
      lastname, 
      email
    }
  }"
}

Welcome to the Edvisor.io GraphQL API! You can use this API to create, read, update, and delete commonly used objects in Edvisor.io.

This Edvisor.io API follows GraphQL (http://graphql.org/).

To access our API, please contact us at support@edvisor.io.

Integrations

An Edvisor Agency account manages information about students, staff tasks and reminders, quotes, invoices, products and services (courses, accommodations, add-ons, fees) offered by “connected” schools, products and services offered by the agency, and student registrations.

This document is provides an overview of the ways you can integrate with your edvisor agency account and the types of data you can push, pull, or synch with. Most commonly, we see Edvisor Agency integrations with 3rd party CRMs (to make quoting and registering students more seamless), B2C Websites (to provide quoting or ecommerce functionality for students online), and accounting systems.

There are three ways to integrate with your Edvisor account.

API integration

This method allows you to update data in your Edvisor account with changes in your external system by calling the Edvisor API.

Webhooks integration

This method allows you to update your external system with changes in your Edvisor account by registering a webhook and subscribing to the relevant events and implementing the necessary logic needed to handle the change event to update your existing system.

API and Webhooks integration

This method allows 2-way synchronization between your Edvisor account and your existing back-office system by combining Method 1 and Method 2.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "https://api.edvisor.io/graphql"
  -H "Authorization: Bearer <your_edvisor_api_key>"

Make sure to replace your_edvisor_api_key with your API key.

Edvisor.io uses API keys to allow access to the API. To access our API, please contact us at support@edvisor.io.

Edvisor.io expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer <your_edvisor_api_key>

Webhooks

Introduction

In addition to the available GraphQL API, Edvisor.io can register webhooks so you can synchronise the data in your agency account with an external service or system. When registering a webhook, you’re able to subscribe to specific events so that you only receive the events (synchronize the data) that you want.

For example, if you’d like keep the student information in your external CRM up-to-date with changes made to students in your Edvisor.io account, you can register a webhook that subscribes to the “student:update” event. When a student is updated on Edvisor.io, we will then send the updated information to a pre-set URL.

Sample Webhook:

Webhook endpoint: https://api.your-agency.com/webhook/edvisor

Events subscribed: student:create, student:update

What happens: When a student is updated or created, we will send a POST https://api.your-agency.com/webhook/edvisor request with a body containing the changes that represent the event.

Responding to a webhook

To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. Any other information returned in the request headers or request body is ignored. All response codes outside this range, including 3xx codes, will indicate to Edvisor.io that you did not receive the webhook. This does mean that a URL redirection or a “Not Modified” response will be treated as a failure.

If a webhook is not successfully received for any reason, Edvisor.io will continue trying to send the webhook once every 15 minutes for up to 3 days.

Available events

Student

School

Offering

Quote

Promotion

Student enrollment

Event Object

The event object that is sent along with the webhook request will be structured like the following:

Sample Event object:

{
  "created": "2017-03-31T19:12:43.687Z",
  "user": {
    "userId": 1,
    "firstname": "John",
    "lastname": "Garcia",
    "email": "john.garcia@education-agency.com"
  },
  "type": "student:update",
  "data": {
    "after": {
      "studentId": 1,
      "email": "frank@email.com"
    },
    "before": {
      "studentId": 1,
      "email": ""
    }
  }
}
Attribute Description
created Timestamp of when this event occured
user Information regarding the creator of this event
user.userId
user.firstname
user.lastname
user.email
type Event name (ie. student:create)
data
data.after The object affected AFTER the event has taken place
data.before the object BEFORE the event took place

API

You can view the full API documentation for our GraphQL API here.

Please note that we are currently using GraphQL which is quite different from typical RESTful API’s. To learn more about how to interact with a GraphQL API, please checkout http://graphql.org/.

To access our API, please contact us at support@edvisor.io.

Errors

Edvisor.io will respond with a 200 success code even if there are operational errors. This follows the GraphQL specification. All errors will be described in an errors array in the response.

#Sample error response

{
  "data": {
    "agencyCompany": null
  },
  "errors": [
    {
      "message": "Unauthenticated",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "agencyCompany"
      ]
    }
  ]
}

Web 2 Leads

Getting started

If you have a wordpress site you can use our plugin to create your form. Please search for ‘edvisor’ in the wordpress plugins.

Setting up a web2lead form on your website requires two steps. First, you must have a form displaying what information you want to collect. Second, you have to send that information to the Edvisor API. We will do that with Javascript.

Please refer to Form Data to find out how to structure your data.

Form setup

img

Basic Form Setup

<form id='edvisor-form'>

  <div>
    <label>First Name *</label>
    <input id='edvisor-firstname' type='text' name='firstname' placeholder='Enter First Name' required />
  </div>

  <div>
    <label>Last Name</label>
    <input id='edvisor-lastname' type='text' name='lastname' placeholder='Enter Last Name' />
  </div>

  <div>
    <label>Email *</label>
    <input id='edvisor-email' type='email' name='email' placeholder='Enter Email' required/>
  </div>

  <div>
    <label>Message</label>
    <textarea id='edvisor-notes' name='notes' placeholder='Let us know what you think'></textarea>
  </div>

  <button type='submit'>Submit</button>
</form>

Here is a basic form. We gave this form an id(identification) of ‘edvisor-form’.

Inside this form we have several fields (First Name, Last Name, Email, Message), and also a submit button.

Each field is structured in the same way. There is a label and an input or textarea with a div around it.

img

The label is the text that shows above an input.

<label> Text Here </label>

The input is where the user can type information. The input below is saying that this is a text field and its name is firstname

<input type='text' name='firstname' />

The placeholder is the text inside of the input, and it disappears when the user starts typing.

<input type='text' name='firstname' placeholder='This text shows inside the field' />

Adding required into the field makes it required. They can’t submit the form without filling in the field. An error message will pop up if they try.

<input type='text' name='firstname' required />

img

If you need help understanding HTML, here is some documentation:

Sending the data

Basic Javascript Setup

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
<script>
  var edvisorFormSending = false;

  $('#edvisor-form').submit(function(event){

    $('#edvisor-message').remove();

    var formData = {
      'agencyId' : '123',
      'firstname' : $('#edvisor-firstname').val(),
      'lastname' : $('#edvisor-lastname').val(),
      'email' : $('#edvisor-email').val(),
      'notes' : $('#edvisor-notes').val(),
    }

    if(!edvisorFormSending) {

      edvisorFormSending = true;

      $.ajax({
        url: 'https://app.edvisor.io/api/v1/student?public_key=YOUR-KEY-HERE',
        data: JSON.stringify(formData),
        type:'PUT',
        contentType: 'application/json; charset=utf-8',
        processData: false
      })
        .done(function() {
          $('#edvisor-form').append('<p id="edvisor-message">Form was submitted!</p>');
          edvisorFormSending = false;
        })
        .fail(function(data) {
          $('#edvisor-form').append('<p id="edvisor-message">Something went wrong!</p>');
          console.log(data)
          edvisorFormSending = false;
        });

    };

    event.preventDefault();

  });
</script>

This Javascript requires two things to work.

It needs to know your:

  1. agencyId (the number assigned to your office by Edvisor)
  2. API key

If you need help finding your agencyId, please go to How to get your agencyId.

You can get your API Key by contacting us at support@edvisor.io

-

After gathering the required information. Please do the following:

If you need help with Javascript, here is some documentation:

How to get your agencyId

  1. Log into Edvisor
  2. Go to your settings
  3. If you have multiple offices, select the office you want.
  4. Look for the ID field, that is your agencyId.

agency

Style your form

#edvisor-form {
  width: 300px;
  font-family: sans-serif;
  font-weight: 100;
  padding: 20px;
}
#edvisor-form div {
  margin-bottom: 15px;
}
#edvisor-form label {
  display: block;
  margin-bottom: 5px;
}
#edvisor-form input,
#edvisor-form textarea {
  width: 100%;
  padding-left: 5px;
  border-radius: 2px;
  border: 1px solid #dfe3e5;
  outline: 0;
}
#edvisor-form input {
  height: 35px;
}
#edvisor-form textarea {
  height: 100px;
}
#edvisor-form ::-webkit-input-placeholder {
  font-family: sans-serif;
  font-weight: 100;
}
#edvisor-form button {
  padding: 10px 20px;
  border-radius: 2px;
  border: 1px solid #dfe3e5;
  background-color: #fff;
  display: block;
  margin-left: auto;
}

The code to the right is the styles of the form above.

Place this into your css file or place it in <style>Code Here</style> and place it above the form.

If you need help styling a form, here is some documentation:

Code Snippit

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>

<style>
#edvisor-form {
  width: 300px;
  font-family: sans-serif;
  font-weight: 100;
  padding: 20px;
}
#edvisor-form div {
  margin-bottom: 15px;
}
#edvisor-form label {
  display: block;
  margin-bottom: 5px;
}
#edvisor-form input,
#edvisor-form textarea {
  width: 100%;
  padding-left: 5px;
  border-radius: 2px;
  border: 1px solid #dfe3e5;
  outline: 0;
}
#edvisor-form input {
  height: 35px;
}
#edvisor-form textarea {
  height: 100px;
}
#edvisor-form ::-webkit-input-placeholder {
  font-family: sans-serif;
  font-weight: 100;
}
#edvisor-form button {
  padding: 10px 20px;
  border-radius: 2px;
  border: 1px solid #dfe3e5;
  background-color: #fff;
  display: block;
  margin-left: auto;
}
</style>

<form id='edvisor-form'>

  <div>
    <label>First Name *</label>
    <input id='edvisor-firstname' type='text' name='firstname' placeholder='Enter First Name' required />
  </div>

  <div>
    <label>Last Name</label>
    <input id='edvisor-lastname' type='text' name='lastname' placeholder='Enter Last Name' />
  </div>

  <div>
    <label>Email *</label>
    <input id='edvisor-email' type='email' name='email' placeholder='Enter Email' required/>
  </div>

  <div>
    <label>Message</label>
    <textarea id='edvisor-notes' name='notes' placeholder='Let us know what you think'></textarea>
  </div>

  <button type='submit'>Submit</button>
</form>

<script>
  var edvisorFormSending = false;

  $('#edvisor-form').submit(function(event){

    $('#edvisor-message').remove();

    var formData = {
      'agencyId' : '123',
      'firstname' : $('#edvisor-firstname').val(),
      'lastname' : $('#edvisor-lastname').val(),
      'email' : $('#edvisor-email').val(),
      'notes' : $('#edvisor-notes').val(),
    }

    if(!edvisorFormSending) {

      edvisorFormSending = true;

      $.ajax({
        url: 'https://app.edvisor.io/api/v1/student?public_key=YOUR-KEY-HERE',
        data: JSON.stringify(formData),
        type:'PUT',
        contentType: 'application/json; charset=utf-8',
        processData: false
      })
        .done(function() {
          $('#edvisor-form').append('<p id="edvisor-message">Form was submitted!</p>');
          edvisorFormSending = false;
        })
        .fail(function(data) {
          $('#edvisor-form').append('<p id="edvisor-message">Something went wrong!</p>');
          console.log(data)
          edvisorFormSending = false;
        });

    };

    event.preventDefault();

  });
</script>

Here is the final code for the form above. After you add in your agencyId and API key as discussed in Sending the data. You should be able to copy and paste this into your website.

Form googlePlaceId

Ajax and Autocomplete for googlePlaceId fields

$("#your-field").autocomplete({
  source: function( request, response ) {
    $.ajax({
      url: 'https://app.edvisor.io/api/v1/google-place/search?public_key=APIKEY',
      type: 'GET',
      data: {
        query: request.term
      },
      success: function(data) {
        response(jQuery.map(data, function(item) {
          return {
            label: item.description,
            id: item.place_id
          };
        }));
      },
    });
  },
  select: function(event, ui) {
    var googleId = ui.item.id
    event.target.setAttribute('data-google', googleId)
  },
  change: function (event, ui) {
    if(ui.item == null || ui.item == undefined) {
      $(this).val("")
    }
  }
});

// prevent hitting the enter button on the google field and accidently submitting the form.
$("#your-field").keypress(function(event) {
  if (event.keyCode == 13) {
    event.preventDefault();
  }
});

If you want to have city or destinations on your form, you will need to do the following.

You will need to load in jQuery Ui if you don’t have an autocomplete library in your code.

<link rel="stylesheet" href="https://ajax.googleapis.com/ajax/libs/jqueryui/1.11.4/themes/smoothness/jquery-ui.css"> <script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.11.4/jquery-ui.min.js"></script>

The code to the right will check to see if what the user types into the selected field matches anything in our database, and if it does, it will show everything that matches in a dropdown. The user can then select an option from the dropdown.

Once the selection is over, it will store the Google Place Id into an attribute on the field called ‘data-google’. You can then select this by

$(your-field).attr('data-google')

Below the ajax get, is a function to disable the enter key when inside the field. We found users were accidently submitting the form when using the auto complete.

Replace your-field with the id of your field. Replace APIKEY with your Api key.

How googlePlaceId works

{
  "currentLocationGooglePlaceId": "ChIJ--IExB6rOQcRZysfWJNymsk",
  "studentLocationPreferences": [
    {
      "googlePlaceId" : "ChIJ--IExB6rOQcRZysfWJNymsk"
    }
  ]
}

Google place id’s is a way to standardize locations around the world. They are used in 'currentLocationGooglePlaceId’ and 'studentLocationPreferences’.

This is what a google place id looks like

ChIJ--IExB6rOQcRZysfWJNymsk

For example Vancouver, BC, Canada is

ChIJs0-pQ_FzhlQRi_OBm-qWkbs

For more documentation or if you want to find id’s to send, please go to Google’s Place ID

Form Data

This is what your data should look like when sending it to Edvisor.

{
  "studentId": 1,
  "agencyId": 1,
  "ownerId": null,
  "nationalityId": null,
  "firstname": "Joe",
  "lastname": "Biden",
  "email": "joebiden@fakemail.com",
  "phone": "555-555-5555",
  "address": null,
  "postalCode": null,
  "gender": "M",
  "birthdate": "2015-06-16T00:00:00.000Z",
  "passportNumber": null,
  "studentStatusId": 1,
  "notes": "Here are some notes about the student...",
  "accommodation": "Homestay",
  "budget": null,
  "startMonth": "01",
  "startYear": "2015",
  "startDay": "25",
  "durationWeekAmount": 10,
  "hoursPerWeek": 25,
  "amOrPm": "AM",
  "currentLocationGooglePlaceId": "ChIJ--IExB6rOQcRZysfWJNymsk",
  "isHighPriority": 0,
  "studentNumber": "fk3k333",
  "studentLocationPreferences": [
    {
      "googlePlaceId" : "ChIJ--IExB6rOQcRZysfWJNymsk"
    }
  ],
  "studentCoursePreferences": [
    {
      "name": "English 101"
    }
  ],
  "studentSchoolPreferences": [
    {
      "name": "Internation School"
    }
  ],
  "customPropertyValues": [
    {
      "customPropertyFieldId": "favorite-color",
      "customOptionSelections": ["Red"]
    },
    {
     "customPropertyFieldId": "best-friend-name",
     "value" : "Kenta"
    }
  ],
  "studentCurrentPipelineStages": [
    {
      "studentPipelineStageId":1160
    }
  ]
}

JSON Request Object

Parameter Required Type Default Description
agencyId Yes Number The ID of the office you want this student to belong to. This can be found in the settings page of Edvisor.io.
ownerId No Number NULL The ID of the user we want to assign the student to. This can be found in the settings page of Edvisor.io. If set to NULL, the student will be left as unassigned.
nationalityId No Number NULL The Country ID of the nationality of the student.
firstname Yes String The first name of the student.
lastname No String NULL The last name of the student.
email No String NULL The email of the student. Note: You can only have one student with the same email in your company.
phone No String NULL The phone number of the student.
address No String NULL The address of your student.
postalCode No String NULL The postal code of your student.
gender No String (M/F) NULL The gender of your student. Accepted values are ’M’ or ‘F’.
birthdate No String (YYYY-MM-DD) NULL The birthdate of your student. Format must be YYYY-MM-DD.
passportNumber No String NULL The passport number of the student.
studentStatusId No Number NULL The first stage in your student pipeline.
notes No String NULL Any notes you wish to keep with the student.
accommodation No String NULL Accommodation goals for the student.
budget No String NULL Budget information
startMonth No Number NULL The numerical value of the month the student wishes to start.
startYear No Number NULL The numerical value of the year the student wishes to start.
startDay No Number NULL The numerical value of the day the student wishes to start.
durationWeekAmount No Number NULL The number of weeks the student wishes to study for.
hoursPerWeek No Number NULL The number of hours per week the student wishes to study for.
amOrPm No String (AM/PM) NULL Whether the student wants to study in the AM or PM.
currentLocationGooglePlaceId No String NULL The Place ID provided by Google’s Places API. This represents where the student is currently residing.
isHighPriority No Boolean false Whether the student should be marked as high priority.
studentNumber No String NULL Any external student number that you wish to store with the student.
studentLocationPreferences No Object[] NULL An array of Google Place IDs which represent the locations that the student wishes to study in.
studentLocationPreferences[].googlePlaceId No String NULL Google Place ID which represent the locations that the student wishes to study in.
studentCoursePreferences No Object[] NULL An array of course names representing the courses that the student wishes to be enrolled in.
studentCoursePreferences[].name No String NULL A course name representing the course that the student wishes to be enrolled in.
studentSchoolPreferences No Object[] NULL An array of school names representing the schools that the student wishes to be enrolled in.
studentSchoolPreferences[].name No String NULL A school name representing the school that the student wishes to be enrolled in.
customPropertyValues No Object[] NULL An array of custom property values to save with the student
customPropertyValues[].customPropertyFieldId Yes String NULL The Custom Property Field ID of the custom property you wish to save
customPropertyValues[].value Yes String NULL The value you want to save with this custom property. This is required ONLY if the custom property is not a dropdown
customPropertyValues[].customOptionSelections[] Yes String[] NULL This is an array of option selections. In the case of a dropdown field, you will only need to pass one value into this array. Note, this is ONLY required if the custom property is a dropdown
studentCurrentPipelineStage No Objecet[] NULL An array of pipeline stage ids representing the pipeline stages.
studentCurrentPipelineStage[].studentPipelineStageId No String NULL A pipeline stage ID represeting the pipeline stage.

Edvisor Fields

agency agency

Nationality

["Andorra","United Arab Emirates","Afghanistan","Antigua and Barbuda","Anguilla","Albania","Armenia","Angola","Antarctica","Argentina","American Samoa","Austria","Australia","Aruba","Azerbaijan","Bosnia and Herzegovina","Barbados","Bangladesh","Belgium","Burkina Faso","Bulgaria","Bahrain","Burundi","Benin","Bermuda","Brunei","Bolivia","Bonaire, Sint Eustatius and Saba","Brazil","The Bahamas","Bhutan","Botswana","Belarus","Belize","Canada","Cocos (Keeling) Islands","Congo","Central African Republic","Congo","Switzerland","Côte d'Ivoire","Cook Islands","Chile","Cameroon","China","Colombia","Costa Rica","Cuba","Cape Verde","Curaçao","Christmas Island","Cyprus","Czech Republic","Germany","Djibouti","Denmark","Dominica","Dominican Republic","Algeria","Ecuador","Estonia","Egypt","Eritrea","Spain","Ethiopia","Finland","Fiji","Micronesia","Faroe Islands","France","Gabon","United Kingdom","Grenada","Georgia","French Guiana","Guernsey","Ghana","Gibraltar","Greenland","Gambia","Guinea","Guadeloupe","Equatorial Guinea","Greece","Guatemala","Guam","Guinea-Bissau","Guyana","Hong Kong","Honduras","Croatia","Haiti","Hungary","Indonesia","Ireland","Israel","Isle of Man","India","Iraq","Iran","Iceland","Italy","Jersey","Jamaica","Jordan","Japan","Kenya","Kyrgyzstan","Cambodia","Kiribati","Comoros","Saint Kitts and Nevis","North Korea","South Korea","Kuwait","Cayman Islands","Kazakhstan","Laos","Lebanon","Saint Lucia","Liechtenstein","Sri Lanka","Liberia","Lesotho","Lithuania","Luxembourg","Latvia","Libya","Morocco","Monaco","Moldova","Montenegro","Madagascar","Marshall Islands","Macedonia","Mali","Myanmar","Mongolia","Macao","Northern Mariana Islands","Martinique","Mauritania","Montserrat","Malta","Mauritius","Maldives","Malawi","Mexico","Malaysia","Mozambique","Namibia","New Caledonia","Niger","Norfolk Island","Nigeria","Nicaragua","Netherlands","Norway","Nepal","Nauru","Niue","New Zealand","Oman","Panama","Peru","French Polynesia","Papua New Guinea","Philippines","Pakistan","Poland","Pitcairn","Puerto Rico","Palestine","Portugal","Palau","Paraguay","Qatar","Réunion","Romania","Serbia","Russia","Rwanda","Saudi Arabia","Solomon Islands","Seychelles","Sudan","Sweden","Singapore","Slovenia","Slovakia","Sierra Leone","San Marino","Senegal","Somalia","Suriname","South Sudan","Sao Tome and Principe","El Salvador","Sint Maarten (dutch Part)","Syria","Swaziland","Turks and Caicos Islands","Chad","Togo","Thailand","Tajikistan","Tokelau","Timor-Leste","Turkmenistan","Tunisia","Tonga","Turkey","Trinidad and Tobago","Tuvalu","Taiwan","Tanzania","Ukraine","Uganda","United States","Uruguay","Uzbekistan","Holy See (Vatican City State)","Saint Vincent and The Grenadines","Venezuela","British Virgin Islands","US Virgin Islands","Vietnam","Vanuatu","Wallis and Futuna","Samoa","Serbia","Yemen","Mayotte","South Africa","Zambia","Zimbabwe","United States Minor Outlying Islands","British Indian Ocean Territory"]

‘nationalityId’ will only accept a number. Use the index number from the array to the right.

If you want “Andorra” to be chosen, set

{'nationalityId': 1}

If you want “Albania” to be chosen, set

{'nationalityId': 6}

Custom Fields

Text or Date field

{
  "customPropertyValues": [
    {
     "customPropertyFieldId": "best-friend-name",
     "value" : "Kenta"
    }
  ]
}

Dropdown field (case-sensitive)

{
  "customPropertyValues": [
    {
      "customPropertyFieldId": "favorite-color",
      "customOptionSelections": ["Red"]
    }
  ]
}

Text and dropdown Field

{
  "customPropertyValues": [
    {
      "customPropertyFieldId": "favorite-color",
      "customOptionSelections": ["Red"]
    },
    {
     "customPropertyFieldId": "best-friend-name",
     "value" : "Kenta"
    }
  ]
}

Custom properties allow you to setup and store any additional fields you want to with a student.

Custom fields are unique to each individual office. When creating new student with custom properties, you must ensure that the office you are assigning the student to has the custom properties that you wish to store with the student.

You can create custom fields in your Settings under the Agency tab.

There are 3 types of custom fields. Text/Dropdown/Date

Please be aware that Dropdown is case sensitive and that you must send the exact text.

When you create a Custom field, you will get a Field ID. Use this ID as your ‘customPropertyFieldId’. Please refer to the right to see how your data should be structured.

agency