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

Authentication

# 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>

You must replace your_edvisor_api_key with your API key.
It is your responsibility to not expose your Edvisor.io API key to the public. All requests to the Edvisor API should be made from your server and not a customer-facing front end.

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

student:create

student:update

student:delete

School Company

school:create

school:update

school:delete

Campus

campus:create

campus:update

campus:delete

Offering

offering:create

offering:update

offering:delete

Start Date Template

startDateTemplate:create

startDateTemplate:update

startDateTemplate:delete

Student Quote

studentQuote:create

studentQuote:update

Event Object

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

In the example to the left, we are using the root query offering to find a specific offering, then traversing through the offeringCourse relation to get to the prices property.

You will notice that the prices property takes in a filter parameter which you can customize to meet your needs. You will notice that the prices property will return a list of DerivedPrice objects, which is described here: http://docs.edvisor.io/schema/derivedprice.doc.html

If you are an agency customer, you have full ability to explore the data of the schools you’re connected to through our API.

To begin, we recommend you start with the agencyCompany query which will return to you data on your own Agency account. From there you can traverse our API in GraphQL to the data of your connected schools.

As an agency customer, you can retrieve data on any of the quotes that you have previously created. Please see the example on the right.

The example to the right shows only how to fetch information for the courses and fees attached to your quote. There are many more objects that you can fetch in addition to course information. Please see the documentation on the following objects for a full description of what data is available to you:

As an agency customer, you can retrieve data on any of the student enrollments that have been created through Edvisor. Please
see the example on the right. Student enrollments are variously called “applications” or “bookings” in the industry.

The example to the right shows only how to fetch information for the courses, accommodations, and services attached to the student enrollment. For more details as to which fields are available on which objects, consult the schema documentation.

As an agency customer, you can retrieve data on any of the invoices that have been created through Edvisor. Please
see the example on the right. You can structure the query to get additional info on the invoice, such as any files
associated with it, any invoice items (referred to as raw items), the invoice type, and the payment currency.

There are two different endpoints to query invoices, either by Invoice Id or using a filtered search.

The following parameters are available for the filtered search:

agencyIds: number []

invoiceIds: number []

externalIds: number []

created: DateOnlyRangeInput

This query also takes a pagination input, which is an object with an offset and a limit field.

The example on the right shows a filtered search using agencyIds and the created parameter.

Web 2 Leads

Getting started

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.

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.

How googlePlaceId works

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

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.

B2C Widget Documentation

Edvisor CDN

Production

The production edvisor app is hosted at https://cdn.edvisor.io/b2c/edvisor-search.js,
Beware, this will be pointing at your production Edvisor Account creating real students, Quotes, and Applications in the system possibly contacting other schools or sending emails to students.

Staging

For setup and testing we recommend using our staging version of the application hosted at https://cdn.edvisor.io/b2c/sandbox/edvisor-search.js. This will point at a replicated version of our system. (The data found on the staging may be outdated.)
You will still be able to log into your Edvisor Account through https://sandbox.edvisor.io with your normal Edvisor credientials.
The stability & speed of the staging system can be less reliable as we are occasionally deploying new features to test to this server.

Configurations

In the table below, use the column Data Type to determine where a value should come from. For example,
startQuoteSelector is an HTML selector. You can read more about HTML Selectors online! On the other
hand, a list of Edvisor Ids must come from Edvisor.

Key

Example Value

Data Type

Description

Required V Optional

startQuoteSelector

#btWidget

HTML selector

Within the rendered HTML page there must be an empty div with this value as it’s id. This allows us somewhere to render the modal.

Required

apiKey

public_1234

Edvisor API Key

This is your api key provided by Edvisor. This allows us to query courses from connected schools, possible location destinations…

Required

studentNationality

jp (Japan)

ISO Country Code

Within the Edvisor system the Student’s nationality is an important value. This will determind certain prices, unlock possible promotions, etc… This value is not used for localization. For more information on ISO country codes, look here

Optional*

studentLanguage

ja (Japanese)

ISO Language Code

At Edvisor we expect people of many different languages to use our system. This value will set the language to be displayed in the system. For more information on ISO language codes, look here. Currently Edvisor only supports a sub-set of these codes, see below.

Required

agencyId

1234

Edvisor Id

On the Edvisor System a company can have many agency offices. This value allows us to know where to add the created student within the Edvisor System.

Required

defaultCourseCategoryIds

[3, 4] (General English, Business English)

List

These values will pre-populate the dropdown for course types

Optional

defaultGooglePlaceIds

['ChIJs0-pQ_FzhlQRi_OBm-qWkbs'] (Vancouver, BC Canada)

List

These values will pre-populate the dropdown for possible study locations. To find Google Place Ids in the Edvisor system look here

Optional

defaultSchoolIds

[1, 2, 3]

List

Passing this parameter will limit the search to these schools, identified by their school ID. The location dropdown will be disabled and the schools will be a static search parameter in the modal.

Optional

redirectUrl

app.html

url

This is the page for viewing results and holding the next part of the Edvisor Application.

Required

gaTrackingId

UA-111111111-1

GoogleAnalytics Id

Used for Analytics through Google Analytics, more information can be found here

Optional

searchBySchool

true

Boolean

If set to true, users will be able to search for courses by school campus, rather than by location. By default, users can search for courses by location.

Optional

requireStudentCurrentCountry

false

Boolean

If set to true, users will be required to choose a country where they currently reside. This value will be used as an additional search parameter when determining available courses and prices. By default, a user’s current country is not required.

Optional

* If no studentNationality is provided a required field will show on the initial student quote modal. An example can be found here

Note that it is an error to use an apiKey that starts with private_. You must only use an apiKey that starts with public_. If you have any questions about this behaviour, please contact Edvisor support.

Usages

You can initialize the modal in Javascript and call the render function within the button onclick. This allows the ability to create many Edvisor widget instances on the same page with each being able to be rendered individually.

Edvisor Search App

Configurations

On the Edvisor System a company can have many agency offices. This value allows us to know where to add the created student within the Edvisor System.

Required

termsUrl

'http://www.example.com'

url

The URL of the terms and agreements for a student signing up with your agency / school

Required

apiKey

public_1234

Edvisor API Key

This is your api key provided by Edvisor. This allows us to query courses from connected schools, possible location destinations…

Required

studentNationality

'ca'

ISO Country Code

Within the Edvisor system the Student’s nationality is an important value. This will determind certain prices, unlock possible promotions, …

Required

studentLanguage

en (English)

ISO Language Code

At Edvisor we expect people of many different languages to use our system. These values will set the language to be displayed in the system.

Required

defaultCourseCategoryIds

[3, 4]

List

These values will pre-populate the dropdown for course types

Optional

defaultGooglePlaceIds

['ChIJs0-pQ_FzhlQRi_OBm-qWkbs'] (Vancouver, BC Canada)

List

These values will pre-populate the dropdown for possible study locations. To find Google Place Ids in the Edvisor system look here

Optional

gaTrackingId

UA-111111111-1

Google Analytics Id

Used for Analytics through Google Analytics, more information can be found here

Optional

selector

#Widget

HTML Selector

A placeholder used for the modal when a user selects to create another quote

Required

searchBySchool

true

Boolean

If set to true, users will be able to search for courses by school campus, rather than by location. By default, users can search for courses by location.

Optional

requireStudentCurrentCountry

false

Boolean

If set to true, users will be required to choose a country where they currently reside. This value will be used as an additional search parameter when determining available courses and prices. By default, a user’s current country is not required.

Optional

requirePhoneNumber

true

Boolean

If set to false, the phone input will not be displayed when capturing the student information before the quote is submitted. If a custom property contact-by-phone is set up for the Agency, then a new checkbox will apear, asking the student if they would like to be contacted by phone. If that box is checked then the phone input will be displayed. For more details see documentation below on this feature. The default is to always require the phone number.

Optional

Usage

This should be added to the redirectUrl page defined in the modal configurations. The page should be primarily empty as the search and results will take up most of the page.

~ Note the HTML definition of the selector must be defined before the script tag, otherwise the selector will not be found. Resulting in the console error, Error: Target container is not a DOM element.

Optional phone number usage

The search app can be configured to make the phone number input optional when capturing the student information. If the flag requirePhoneNumber is set to false we can also capture information on whether the student would like to be contacted by phone. In order to do so, the agency must configure a custom property to capture the student’s preference. In the Edvisor app, under the settings for offices, a new custom property must be added with the following key: contact-by-phone. The field must be a dropdown with possible values of Yes and No (ensure case matches). With this setup, when the student gets to the final step of submitting the quote, there will be an additional checkbox prompting them on their preference on whether they would like to be contacted by phone. If they tick the box then the input for the phone number will appear.

Optional custom agreements

The app can also be configured to present custom agreements to the user. There are two steps required to use custom agreements:

Create custom properties through the Edvisor App

Add an agreements attribute to the app configuration containing agreement objects with IDs corresponding to the newly created custom properties.

Agreement objects have three attributes:

label: defines the text that will appear next to the agreement checkbox

required: determines whether or not the quote process can be completed without checking the agreement checkbox

customPropertyFieldId: is the customPropertyFieldId of the custom property created through the Edvisor app to support the custom agreement

For example, to add two custom agreements to the app, you would first create custom properties with ids of 'promotion' and 'new-terms'. The custom properties must be of type dropdown, and have values Yes and No. Next you would add an agreements object to the app configuration as shown in the example to the right.

Styling

Style rules used in the edvisor B2C Widget are always of the form:

.edvisor_app-container.edvisor_app-inner{/* ... styles */}

This guarantees that B2C’s internal styles will only affect elements on the page that are contained within the .edvisor_app-container element. All class names used within B2C are prefixed with edvisor_, which makes it unlikely
that an external style from the host site will accidentally change the appearance of the B2C widget.

Modal Overlay

The CSS rule z-index maintains the order in which elements are displayed from front to back. Unfortunately there is
no way of guaranteeing that an element will be “the topmost” on a page. We have defined the semi-opaque grey modal overlay
used throughout the B2C app as having a z-index of 9999, since a value over 9000 will win in most cases. However, if the
host website uses z-index greater than 9999 the modal overlay will appear below those elements. To fix this issue, override
the value by defining a custom css rule on the host site:

Searching for a General English course in Auckland, starting after October 25th with a duration of at least 4 weeks, for an 18 year old student

Analytics

A users flow through the application can be tracked by passing the optional gaTrackingId property into the snippits. This Tracking Id will be provided by Google Analytics and can be found under Admin -> Your Account -> Track Info. This will allow you to use Google Analytics within the app in the same way you would with it embeded in a website

Page

Stage description

/start-quote-modal

A user has triggered the startQuote modal to show

/

Course results / course selection page

/course-customization

Accommodation & Service Selection page, this also includes the lead generation

/review-quote

Review quote page, email quote, contact Advisor

/course-registration

Filling out the registration information

/thank-you

User has completed the entire app flow

GA User Id

// retrieve the gaUserId and use it to initialize the appga(function(tracker){Edvisor.widgets.CourseSearchApp.newInstance().render({gaUserId:tracker.get('clientId'),// rest of configuration});

It is possible to associate app users with students in the Edvisor database. To use this feature, you must retrieve the gaUserId from the browser’s cookies, and use this value to initialize the app.
The gaUserId and gaTrackingId are stored alongside student information as metadata, and can be queried via the Edvisor Graphql API.

Google Place Id’s

Google Place Ids can be retrieved on the Edvisor system by curling our API with the city name you wish to find the google place id for. This will return a Google Place JSON object, within which the placeId can be found.

Supported Language Codes

Edvisor uses ISO language and country codes. In some cases we need to represent multiple
languages from the same family or group whose usage differs by region. In this case, we
disambiguate the language code by appending the country code. For example, Spanish spoken
in Colombia differs from that spoken in Spain so we use the compound es_co to represent “Colombian Spanish”.

At this time, Edvisor only provides translations for the following languages (alphabetically):

ISO Language Name

Code

Albanian

sq

Arabic

ar

Chinese

zh

English

en

French

fr

German

de

Italian

it

Japanese

ja

Korean

ko

Polish

pl

Portuguese

pt

Russian

ru

Spanish (Castilian)

es-es

Spanish (Colombia)

es-co

Thai

th

Notes

Currenty to track if the student has selected to be contacted about future promotions we need the connected agency to create a dropdown custom field. This field should look like this, with the important pieces being the Field ID must be “promotion” and the options must be Yes & No. At this time if the custom field is not found you will see an error when clicking on Get Quote that says Cannot read property 'fieldTypeId' of null.