NAV
shell

Introduction

Welcome to the BETA Edvisor.io API! You can use our API to access endpoints which can get, create, update, or delete information stored in the Edvisor.io application.

You can view code examples in the dark area to the right.

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

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: private_key=\"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: private_key="your_edvisor_api_key"

Student

Create a student

curl "https://app.edvisor.io/api/v1/student"
  -H "Authorization: private_key=\"your_edvisor_api_key\"; Content-Type: application/json" 
  -X POST 
  -d '{}' //your json parameters

The above command returns JSON structured like this:

{
  "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
    }
  ]
}

This endpoint will create a student.

HTTP Request

POST https://app.edvisor.io/api/v1/student

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

googlePlaceId

{
  "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

Student Status

List all student statuses

curl "https://app.edvisor.io/api/v1/student-status/list?filter={"where":{"agencyId":92}}"
  -H "Authorization: private_key=\"your_edvisor_api_key\""

The above command returns JSON structured like this:

{
  "metadata": {
    "total": 10
  },
  "data": [{
    "studentStatusId": 795,
    "agencyId": 92, 
    "label": "Lead", 
    "position": 0,
    "studentCount": 1,
    "studentStatusSteps":[]
  }, {
    "studentStatusId": 796,
    "agencyId": 92,
    "label": "Deciding",
    "position": 1,
    "studentCount": 6,
    "studentStatusSteps": []
  },
  ...
  ]
}

This endpoint will list all the student statuses.

HTTP Request

GET https://app.edvisor.io/api/v1/student-status/list

Example

GET https://app.edvisor.io/api/v1/student-status/list?filter={"where":{"agencyId":92}}

URL Parameters

Parameter Required Default Description
filter Yes false A JSON Object.
filter.where Yes false A JSON Object.
filter.where.agencyId Yes false The Agency ID to filter the student statuses.

Country

List all countries

curl "https://app.edvisor.io/api/v1/country"
  -H "Authorization: private_key=\"your_edvisor_api_key\""

The above command returns JSON structured like this:

[
  {
    "countryId": 1, 
    "code": ad,
    "continent": "EUROPE",
    "currencyId": 43,
    "languageId": null,
    "nameTranslationId": 37431
    }, {
    "countryId": 2, 
    "code": ae,
    "continent": "ASIA",
    "currencyId": 1,
    "languageId": null,
    "nameTranslationId": 37432
  },
  ...
]

This endpoint will list all the countries.

HTTP Request

GET https://app.edvisor.io/api/v1/country

URL Parameters

(None)

Errors

The Edvisor.io API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
403 Forbidden – The resource requested is not available to you
404 Not Found – The specified resource could not be found
500 Internal Server Error – We had a problem with our server. Try again later.

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 Create a Student 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(d
          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(d
          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.