NAV

Introduction

Sample GraphQL Request:

POST https://api-v2.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-v2.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 Company

Campus

Offering

Start Date Template

Student Quote

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

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

API Reference

Graphql Schema

GraphQL Playground

GraphQL Playground is a web tool to explore Edvisor api and test drive queries and mutations.

https://www.graphqlbin.com/

Use

https://api-v2.edvisor.io/graphql

as the endpoint URL

Agency API Guide

Detailed explanation and examples to using Edvisor Api as an Agency

Viewing a Quote

To fetch all the course information on a quote

query {
  studentQuote(studentQuoteId:1) {
    studentQuoteId
    studentQuoteOptions {
      studentQuoteOptionItems {
        __typename

        ... on StudentQuoteOptionCourseItem {
          offeringPriceItem {
            durationAmount
            durationType {
              codeName
            }
            startDate
            endDate
            priceAmount
            priceCurrency {
              code
            }
          }
          courseSnapshot {
            offeringCourseCategory {
              codeName
            }
            name
          }
        }
      }
    }
  }
}

You can copy and paste this cURL command to test it out!

curl 'https://api-v2.edvisor.io/graphql' 
  -H 'Authorization: Bearer <your_edvisor_api_key>' \
  -H 'Content-Type: application/json' \
  --data-binary '{"query":"query {\n  studentQuote(studentQuoteId:<your_quote_id>) {\n    studentQuoteId\n    studentQuoteOptions {\n      studentQuoteOptionItems {\n        __typename\n        \n        ... on StudentQuoteOptionCourseItem {\n          offeringPriceItem {\n            durationAmount\n            durationType {\n              codeName\n            }\n            startDate\n            endDate\n            priceAmount\n            priceCurrency {\n              code\n            }\n          }\n          courseSnapshot {\n            offeringCourseCategory {\n              codeName\n            }\n            name\n          }\n        }\n      }\n    }\n  }\n}","variables":null}' 
  --compressed

To fetch all the fee information on a quote

query {
  studentQuote(studentQuoteId:1) {
    studentQuoteId
    studentQuoteOptions {
      studentQuoteOptionItems {
        __typename

        ... on StudentQuoteOptionFeeItem {
          appliedFeePriceItem {
            startDate
            endDate
            priceAmount
            priceCurrency {
              code
            }
          }
          feeSnapshot {
            name
          }
        }
      }
    }
  }
}

You can copy and paste this cURL command to test it out!

curl 'https://api-v2.edvisor.io/graphql' 
  -H 'Authorization: Bearer <your_edvisor_api_key>' \
  -H 'Content-Type: application/json' \
  --data-binary '{"query":"query {\n  studentQuote(studentQuoteId:<your_quote_id>) {\n    studentQuoteId\n    studentQuoteOptions {\n      studentQuoteOptionItems {\n        __typename\n        \n        ... on StudentQuoteOptionFeeItem {\n          appliedFeePriceItem {\n            startDate\n            endDate\n            priceAmount\n            priceCurrency {\n              code\n            }\n          }\n          feeSnapshot {\n            name\n          }\n        }\n      }\n    }\n  }\n}","variables":null}' 
  --compressed

To fetch almost everything on a quote

query ($studentQuoteId: Int!) {
  studentQuote(studentQuoteId: $studentQuoteId) {
    studentQuoteId
    # optional: add any student quote field
    studentQuoteStatus {
      studentQuoteStatusId
      codeName
    }
    agency {
      agencyId
      # optional: add any agency field
    }
    student {
      studentId
      # optional: add any student field
    }
    agentUser {
      userId
      # optional: add any user field 
    }
    language {
      code
    }
    filterStudentCurrentCountry {
      countryId
      code
    }
    filterEligibleStudentNationalityCountry {
      countryId
      code
    }
    studentQuoteOptions {
      name
      isAccepted
      totalPrice
      priceCurrencyId
      notes
      priceCurrency {
        currencyId
        code
        symbol
      }
      studentQuoteOptionItems {
        ... on StudentQuoteOptionCourseItem {
          studentQuoteOptionItemId
          studentQuoteOptionItemTypeId
          studentQuoteOptionItemType {
            studentQuoteOptionItemTypeId
            codeName
          }
          isAgencyItem
          offeringPriceItem {
            offeringId
            durationAmount
            durationTypeId
            startDate
            endDate
          }
          courseSnapshot {
            offeringId
            offeringCourseCategoryId
            name
          }
        }
        ... on StudentQuoteOptionAccommodationItem {
          studentQuoteOptionItemId
          studentQuoteOptionItemTypeId
          studentQuoteOptionItemType {
            studentQuoteOptionItemTypeId
            codeName
          }
          isAgencyItem
          offeringPriceItem {
            offeringId
            durationAmount
            durationTypeId
            startDate
            endDate
          }
          accommodationSnapshot {
            offeringId
            offeringAccommodationCategoryId
            bathroomTypeId
            roomTypeId
            mealTypeId
            name
          }
        }
        ... on StudentQuoteOptionServiceItem {
          studentQuoteOptionItemId
          studentQuoteOptionItemType {
            codeName
          }
          isAgencyItem
          offeringPriceItem {
            offeringId
            durationAmount
            durationTypeId
            startDate
            endDate
          }
          serviceSnapshot {
            offeringId
            serviceQuantity
            name
          }
        }
        ... on StudentQuoteOptionFeeItem {
          studentQuoteOptionItemId
          studentQuoteOptionItemType {
            codeName
          }
          isAgencyItem
          appliedFeePriceItem {
            feeId
            appliedToOfferingId
            durationAmount
            durationTypeId
            startDate
            endDate
          }
          feeSnapshot {
            feeId
            name
          }
        }
        ... on StudentQuoteOptionDiscountItem {
          studentQuoteOptionItemId
          studentQuoteOptionItemType {
            codeName
          }
          isAgencyItem
          promotionSnapshot {
            promotionId
            name
          }
          appliedDiscountPriceItem {
            ... on AppliedAmountOffDiscountPriceItem {
              promotionId
              promotion {
                name
              }
              priceAmount
              priceCurrency {
                currencyId
                code
                symbol
              }
              appliedToOffering {
                offeringId
                # optional: add any field on an offering
              }
              appliedToFee {
                feeId
                # optional: add any fee field
              }
              endDate
            }
            ... on AppliedDurationExtensionDiscountPriceItem {
              promotionId
              priceAmount
              priceCurrency {
                currencyId
                code
                symbol
              }
              endDate
              extensionDurationType {
                durationTypeId
                codeName
              }
              extensionDurationAmount
              promotion {
                name
              }
              appliedToOffering {
                offeringId
                # optional: add any offering field
              }
            }
            ... on AppliedCustomDiscountPriceItem {
              promotionId
              promotion {
                name
              }
              appliedToOffering {
                offeringId
                # optional: add any offering field
              }
              endDate
              discountDescription
            }
            # ... on moreDiscountPriceItem types will be supported in the future
          }
        }
      }
      studentQuoteOptionFiles {
        fileId
        uploaderUserId
        mimeType
        fileExtension
        name
        path
        url
      }
    }
  }
}

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:

Viewing a StudentEnrollment

To fetch all the salient details of a student enrollment

query {
  studentEnrollment(studentEnrollmentId: 1) {
    studentEnrollmentId
    agencyOwnerId
    sent
    studentEnrollmentOfferingItems {
      ... on StudentEnrollmentOfferingCourseItem {
        offeringTypeId
        courseSnapshot {
          offeringCourseCategory {
            offeringCourseCategoryId
            codeName
          }
          name
        }
      }
      ... on StudentEnrollmentOfferingCourseItem {
        accommodationSnapshot {
          bathroomType {
            bathroomTypeId
            codeName
          }
          offeringId
          offeringAccommodationCategoryId
          name
        }
      }
      ... on StudentEnrollmentOfferingServiceItem {
        offeringTypeId
        serviceSnapshot {
          offeringId
        }
      }
    }
  }
}

You can copy and paste this cURL command to test it out!

curl 'https://api-v2.edvisor.io/graphql' 
  -H 'Authorization: Bearer <your_edvisor_api_key>' \
  -H 'Content-Type: application/json' \
  --data-binary '{"query":"query {\n  studentQuote(studentQuoteId: 42157) {\n    studentQuoteId\n\n    studentQuoteOptions {\n      studentQuoteOptionId\n      \n      studentQuoteOptionItems {\n        ... on StudentQuoteOptionCourseItem {\n          studentQuoteOptionId\n        }\n      }\n    }\n  }\n  \n  studentEnrollment(studentEnrollmentId: 11722) {\n    studentEnrollmentId\n    studentEnrollmentStatusId\n    studentEnrollmentDecisionStatusId\n    schoolId\n    studentId\n    invoiceId\n    quoteId\n    languageId\n    obscuredId\n    studentSignature\n    signedDate\n    specialInstructions\n    created\n    modified\n    agencyOwnerId\n    schoolOwnerId\n    sent\n    isDeletedByAgency\n    isDeletedBySchool\n    studentEnrollmentOfferingItems {\n      ... on StudentEnrollmentOfferingAccommodationItem {\n        accommodationSnapshot {\n          offeringId\n          offeringAccommodationCategoryId\n          name\n        }\n      }\n      ... on StudentEnrollmentOfferingCourseItem {\n        offeringTypeId\n        studentEnrollmentOfferingItemId\n        courseSnapshot {\n          offeringId\n          offeringCourseCategoryId\n          name\n        }\n      }\n    }\n  }\n}","variables":null}'
  --compressed

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.

Viewing an Invoice

Fetch invoices by ID or based on a filtered search

query {
    invoice(invoiceId: 1) {
      invoiceId
      externalId
      invoiceTypeId
      ownerId
      studentId
      studentNationalityId
      studentMinAge
      studentMaxAge
      partnershipId
      invoiceStatusId
      invoicePaymentStatusId
      isOverdue
      notes
      viewed
      issued
      expires
      paymentCurrencyId
      depositCurrencyId
      depositAmount
      depositIsPercentage
      depositDateDue
      depositIsRequired
      languageId
      obscuredId
      createdByUserId
      lastUpdatedByUserId
      created
      modified
    rawItems {
      invoiceItemId
      invoiceId
      invoiceItemTypeId
      offeringId
      promotionId
      snapshotPromotionTypeId
      snapshotExtensionDurationTypeId
      snapshotFreeDurationAmount
      snapshotBonusDurationAmount
      snapshotPromotionApplicableTypeId
      snapshotPromotionSecondaryTypeId
      snapshotPromotionPercentage
      feeId
      isAgencyItem
      isGlobalFee
      position
      school
      program
      durationAmount
      durationTypeId
      notes
      startDate
      endDate
      googlePlaceId
      currencyId
      amount
      isAmountPerDuration
      serviceFeeMultiplier
      partnershipId
      partnershipOfferingId
      created
      modified
    }
    invoiceFiles {
      fileId
      uploaderUserId
      mimeType
      fileExtension
      name
      path
      url
      created
      modified
    }
    invoiceType {
      invoiceTypeId
      codeName
    }
    paymentCurrency {
      currencyId
      code
      symbol
      oneUsd
      enabled
      created
      modified
    }
    } 
}

You can copy and paste this cURL command to test it out!

curl 'https://api-v2.edvisor.io/graphql' 
  -H 'Authorization: Bearer <your_edvisor_api_key>' \
  -H 'Content-Type: application/json' \
  --data-binary '{"query":"query {\n\tinvoice(invoiceId: 24157) {\n\t  invoiceId\n\t  externalId\n\t  invoiceTypeId\n\t  ownerId\n\t  studentId\n\t  studentNationalityId\n\t  studentMinAge\n\t  studentMaxAge\n\t  partnershipId\n\t  invoiceStatusId\n\t  invoicePaymentStatusId\n\t  isOverdue\n\t  notes\n\t  viewed\n\t  issued\n\t  expires\n\t  paymentCurrencyId\n\t  depositCurrencyId\n\t  depositAmount\n\t  depositIsPercentage\n\t  depositDateDue\n\t  depositIsRequired\n\t  languageId\n\t  obscuredId\n\t  createdByUserId\n\t  lastUpdatedByUserId\n\t  created\n\t  modified\n    rawItems {\n      invoiceItemId\n      invoiceId\n      invoiceItemTypeId\n      offeringId\n      promotionId\n      snapshotPromotionTypeId\n      snapshotExtensionDurationTypeId\n      snapshotFreeDurationAmount\n      snapshotBonusDurationAmount\n      snapshotPromotionApplicableTypeId\n      snapshotPromotionSecondaryTypeId\n      snapshotPromotionPercentage\n      feeId\n      isAgencyItem\n      isGlobalFee\n      position\n      school\n      program\n      durationAmount\n      durationTypeId\n      notes\n      startDate\n      endDate\n      googlePlaceId\n      currencyId\n      amount\n      isAmountPerDuration\n      serviceFeeMultiplier\n      partnershipId\n      partnershipOfferingId\n      created\n      modified\n    }\n    invoiceFiles {\n      fileId\n      uploaderUserId\n      mimeType\n      fileExtension\n      name\n      path\n      url\n      created\n      modified\n    }\n    invoiceType {\n      invoiceTypeId\n      codeName\n    }\n    paymentCurrency {\n      currencyId\n      code\n      symbol\n      oneUsd\n      enabled\n      created\n      modified\n    }\n\t} \n}","variables":null}'
  --compressed

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:

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.

The created parameter can take the following filters: 

query {
  invoiceList(
  pagination: { limit: 100, offset:0 }, 
  filter: {
    agencyIds: [1, 2],
    created: {
      gt: "2018-01-31"
    }
  }) {
    count
    data {
      ...
    } 
  }

}

For more details as to which fields are available on which objects, consult the schema documentation.

Agency Company Currency Exchange Rates

Easily query your Agency Company Exchange Rates and update them as needed

This is an example query object with details on the fromCurrency object

  agencyCompanyCurrencyRates {
    agencyCompanyId
    fromCurrencyId
    toCurrencyId
    rate
    created
    modified
    fromCurrency {
      currencyId
      code
      symbol
      oneUsd
      enabled
      created
      modified
    }
  }

You can copy and paste the following cURL command to test it out

curl 'https://api-v2.edvisor.io/graphql' 
  -H 'Authorization: Bearer <your_edvisor_api_key>' \
  -H 'Content-Type: application/json' \
  -data-binary '{"query":"query {\n  agencyCompanyCurrencyRates {\n    agencyCompanyId\n    fromCurrencyId\n    toCurrencyId\n    rate\n    created\n    modified\n    fromCurrency {\n      currencyId\n      code\n      symbol\n      oneUsd\n      enabled\n      created\n      modified\n    }\n  }\n}","variables":{"input":{"fromCurrencyId":8,"toCurrencyId":157,"rate":0.2}},"operationName":null}' 
  --compressed

As an agency customer you can make a query to receive the exchange rates set by your agency. The query takes no parameters, and returns all the existing exchange rates for your Agency.

For more details as to which fields are available on which objects, consult the schema documentation.

Using the currency API you can also update the exchange rates for your Agency Company. The endpoint takes an array of objects, so you can update multiple currencies with one simple request.

Examples of how to use the upsertAgencyCompanyCurrencyRates endpoint and its expected input are on the right.

The input to update the currencies is as follows:

{
    "fromCurrencyId": 8,
    "toCurrencyId": 157,
    "rate": 0.2
  }

Alternatively, if you do not know the IDs for each currency, you can use the currency code (all caps). For example:

{
    "fromCurrencyCode": "CAD",
    "toCurrencyCode": "USD",
    "rate": 0.75
}

You can use either the currency code or the ID. Here is an example of a cURL request to update two currencies:

curl 'https://api-v2.edvisor.io/graphql' 
  -H 'Authorization: Bearer <your_edvisor_api_key>' \
  -H 'Content-Type: application/json' \
  --data-binary '{"query":"mutation updateCurrencyRate($input: [AgencyCompanyCurrencyRateInput]){\n  upsertAgencyCompanyCurrencyRates(input: $input) {\n    agencyCompanyId\n    fromCurrencyId\n    toCurrencyId\n    rate\n    created\n    modified\n  }\n}","variables":{"input":[{"fromCurrencyId":8,"toCurrencyCode":"XPF","rate":69.8},{"fromCurrencyId":8,"toCurrencyId":154,"rate":42.69},{"fromCurrencyId":8,"toCurrencyId":155,"rate":19.69}]},"operationName":"updateCurrencyRate"}' 
  --compressed

School API Guide

Detailed explanation and examples to using Edvisor Api as a School

Web Quotes Engine

The web quotes engine is a plugin that enables students and agents from unconnected agencies to quote a school directly through their website. The quotes and student leads generated by the web quotes engine are accessible through the following queries.

Query a list of your web quotes

The schoolQuoteList query returns a list of the quotes that students or agents have made via the web-quotes engine. The quotes will always include some basic student information. If an agent made the quote on behalf of a student, then the quote will additionally contain some information about the agency.

To see the full schema for this and other queries, use the graphql playground.

Including student data

Query to fetch a list including student data

query {
  schoolQuoteList {
    data {
      studentFirstName
      studentLastName
      studentEmail
      studentAge

      studentNationality {
        code
        nameTranslation(languageCode: EN)
      }
    }
  }
}

Regardless of whether the quote was generated by a student or an agent on behalf of a student, there will be a minimum amount of student data available, such as an email address and nationality. When querying the nationality remember to include the languageCode if you want to view the country name in another language.

Including agency information

Query to fetch a list of quotes including agency information

query {
  schoolQuoteList {
    data {
      agencyName
      agencyEmail

      agencyLocationCountry {
        code
        nameTranslation(languageCode: EN)
      }

      agencyRecruitsFromCountries {
        code
        nameTranslation(languageCode: EN)
      }  
    }
  }
}

If the quote was created by an agent, then they will have been asked to include some additional information about their agency such as an email address at which they can be contacted.

Including Pricing Information

Query to fetch a list of quotes including pricing info

query {
  schoolQuoteList {
    data {
      totalPriceAmount
      currency {
        code
        oneUsd
      }
      quotablePrices {
        ... on CoursePriceItem {
          offering {
            name
          }
          originalPriceAmount
          priceAmount
        }
        ... on AccommodationPriceItem {
          offering {
            name
          }
          originalPriceAmount
          priceAmount
        }
        ... on ServicePriceItem {
          offering {
            name
          }
          serviceQuantity
          originalPriceAmountTimesQuantity
          priceAmountTimesQuantity
        }
      }
    }
  }
}

Web quotes are saved with all of the pricing information necessary to render them on the front-end or create an accurate invoice. When querying for the pricing information you will generally need to query the totalPriceAmount to show the total, and the quotablePrices to show the line items.

The originalPriceAmount and priceAmount represent the line item price before and after promotions have been applied. The currency field contains information about the currency that the quote was made in.

The quotablePrices are a graphql union type. This is because the information associated with different kinds of line items is different. For example, servicePriceItems have a serviceQuantity field. There are three kinds of quotablePrice which you can see in the code listing to the right. The ... on Name syntax is graphql’s way of differentiating between the fields available in the elements of the union.

In addition to the offering name and price information, the QuotePriceItem is a robust object with many relations. You can use this object to get a more detailed breakdown of the price, including individual fees and discounts, as well as information about the line item such as duration, amount, and start date. Since the QuotePriceItem has access to the offering, you can also drill down into the offering to get all kinds of additional information. It is recommended that you experiment with the graphiql explorer to familiarize yourself with the schema.

Pagination & Filters

Query that includes the pagination and filter objects

query {
  schoolQuoteList(pagination: {
    limit: 3,
    offset:0
  }, filter:{
    schoolIds:[21],
    orderBy:studentLastName,
    orderDir:asc
  }) {
    data {
      studentLastName
      studentEmail

      school {
        schoolId
        name
      }
    }
  }
}

The schoolQuoteList query supports pagination and filters to control which quotes and how many are returned.

Pagination

The pagination object accepts a limit, which determines how many results will be returned per page, and an offset which is the index of the first result that you wish to show.

Filters

At the time of this writing the filter object accepts a list of schoolIds and also accepts a property to order the results by.

Query a specific web quote by id

Query a singe school quote by it’s unique id

query {
  schoolQuote(schoolQuoteId: 11) {
    schoolQuoteId
    studentLastName
    studentEmail

    school {
      schoolId
      name
    }
  }
}

Once you have used the list query to get a list of quotes you can use the schoolQuote query to get just one quote by id. Thus together the two endpoints can be used to create a listing page and a view page, for example.

To see the full schema for this and other queries, use the graphql playground.

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

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://api-v1.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://api-v1.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://api-v1.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
studentCurrentPipelineStages No Object[] NULL An array of pipeline stage ids representing the pipeline stages.
studentCurrentPipelineStages[].studentPipelineStageId No String NULL A pipeline stage ID representing 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