StudyAbroad101 API Documentation

Authentication

In order to use the API you need an API USER and an API KEY; Each resource can handle one or more of the following HTTP methods : GET, PUT, DELETE, POST. There are several required HTTP headers : - X-A101-Date - in RFC 2822 format - for example: Thu, 11 Jul 2013 14:23:08 +0000 (please see http://www.ietf.org/rfc/rfc2822.txt for details on this format) Note: the date / time must be GMT timezone based. - X-A101-User - for example: studyabroad101_api_user - X-A101-Auth - for example: of+LxjLsAGY4x0ob8sbGKVo2FiQ=

The value of X­A101­Auth header is used for authentication of the request. See below the way this header is constructed: step 1 : signature_string = concatenate strings (HTTP verb , Query String , X­A101­User header value , X-A101-Date header value); Note: Query String must have no starting “/”, and must be separated by a single “/” from the X­A101­User string. E.g: if the request is GET /students/?filters[id]=1111, the signature_string will look like below: GETstudents/?filters[id]=1111/X­A101­UserThu, 11 Jul 2013 14:23:08 +0000 (where instead of “X­A101­User” will be used the real API USER). step 2 : X­A101­Auth header value = HMAC­SHA1 (API KEY, signature_string) The HMAC­SHA1 algorithm is explained in detail here: http://en.wikipedia.org/wiki/HMAC#Implementation Possible authentication errors - AuthHeaderMissing - this means that the X­A101­Auth header was not detected in your request - AuthTimeDifference - this means that the time difference between the request time and our server time is greater than allowed time Please read the important note below. - ClientHeaderMissing - this means that the X­A101­Client header was not detected in your request - DateHeaderMissing - this means that the Date header was not detected in your request - InvalidClient - the supplied API USER is not registered with our system - InvalidSignature - the supplied signature in X-A101-Auth header is wrong.  Possible reasons are: the signature_string was not properly computed, the HMAC algorithm was not properly calculated, the API KEY is wrong or not valid

Important: because the signature string relies on a timestamp it is very important to have your server/system  time synchronized with a NTP server.

The web service allows 60 seconds time differences between the request date and server date.

Leads

Getting a list of leads

Endpoint

GET api/leads

Parameters

Name Description
created_after Date filter; return all results created after this date
created_before Date filter; return all results created before this date
program_id Program filter; return all results with this program id
offset Offset filter; return results starting from offset
limit Limit filter; return only a specific number of results; default 20

Request

Route

GET api/leads

Headers

X-A101-Date: Wed, 23 Sep 2015 17:43:53 GMT
X-A101-User: sample-provider-1
X-A101-Auth: hPUPtKmV/Nmpdhx4cMFAzKNj4X4=
Message: GETapi/leads/sample-provider-1Wed, 23 Sep 2015 17:43:53 GMT
Host: example.org
Cookie:

Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-UA-Compatible: IE=Edge,chrome=1
ETag: "ad54385da4995fff05d245a03761f6f8"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 392c2191de9416471bffabee8a85556f
X-Runtime: 0.150151
Content-Length: 814

Body

[
  {
    "id": 1,
    "email": "Sample Lead Email 1",
    "name": "Sample Lead Name 1",
    "university": "Sample University 1",
    "comment": null,
    "address": "",
    "study_period": "Sample Study Period 1",
    "program_id": 1,
    "program_name": "Sample Program 1",
    "program_link": "http://example.org/programs/sample-program-1",
    "created_at_string": "09/23/2015",
    "catalog_requested": "No",
    "phone_call_requested": "No",
    "phone_number": "",
    "lead_type": "Info"
  },
  {
    "id": 3,
    "email": "Sample Lead Email 3",
    "name": "Sample Lead Name 3",
    "university": "Sample University 3",
    "comment": null,
    "address": "",
    "study_period": "Sample Study Period 3",
    "program_id": 1,
    "program_name": "Sample Program 1",
    "program_link": "http://example.org/programs/sample-program-1",
    "created_at_string": "09/23/2015",
    "catalog_requested": "No",
    "phone_call_requested": "No",
    "phone_number": "",
    "lead_type": "Application"
  }
]

Getting a list of leads filtered by date

Endpoint

GET api/leads

Parameters

Name Description
created_after Date filter; return all results created after this date
created_before Date filter; return all results created before this date
program_id Program filter; return all results with this program id
offset Offset filter; return results starting from offset
limit Limit filter; return only a specific number of results; default 20

Request

Route

GET api/leads?created_after=2015-08-23&created_before=2015-08-25

Headers

X-A101-Date: Wed, 23 Sep 2015 17:43:53 GMT
X-A101-User: sample-provider-3
X-A101-Auth: Z/ccw+XOddOAE7Er0VKXRi40s9w=
Message: GETapi/leads?created_after=2015-08-23&created_before=2015-08-25/sample-provider-3Wed, 23 Sep 2015 17:43:53 GMT
Host: example.org
Cookie:

Query Parameters

created_after=2015-08-23
created_before=2015-08-25

Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-UA-Compatible: IE=Edge,chrome=1
ETag: "0d8098fa75ebc42a15e51fac47cf252b"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 809e3f2814a3b1101ae1c114bfa8d138
X-Runtime: 0.013257
Content-Length: 411

Body

[
  {
    "id": 7,
    "email": "Sample Lead Email 7",
    "name": "Sample Lead Name 7",
    "university": "Sample University 7",
    "comment": null,
    "address": "",
    "study_period": "Sample Study Period 7",
    "program_id": 3,
    "program_name": "Sample Program 3",
    "program_link": "http://example.org/programs/sample-program-3",
    "created_at_string": "08/24/2015",
    "catalog_requested": "No",
    "phone_call_requested": "No",
    "phone_number": "",
    "lead_type": "Application"
  }
]

Getting a list of leads filtered by program

Endpoint

GET api/leads

Parameters

Name Description
created_after Date filter; return all results created after this date
created_before Date filter; return all results created before this date
program_id Program filter; return all results with this program id
offset Offset filter; return results starting from offset
limit Limit filter; return only a specific number of results; default 20

Request

Route

GET api/leads?program_id=7

Headers

X-A101-Date: Wed, 23 Sep 2015 17:43:55 GMT
X-A101-User: sample-provider-5
X-A101-Auth: jcxuSrwsoS2BU+mQb9OIpU/Z8A4=
Message: GETapi/leads?program_id=7/sample-provider-5Wed, 23 Sep 2015 17:43:55 GMT
Host: example.org
Cookie:

Query Parameters

program_id=7

Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-UA-Compatible: IE=Edge,chrome=1
ETag: "c6eb35f815eccf77422a4573a8a1ecf0"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 135f1d396e6cd9dbb45b920b99cc239a
X-Runtime: 0.018943
Content-Length: 416

Body

[
  {
    "id": 11,
    "email": "Sample Lead Email 11",
    "name": "Sample Lead Name 11",
    "university": "Sample University 11",
    "comment": null,
    "address": "",
    "study_period": "Sample Study Period 11",
    "program_id": 7,
    "program_name": "Sample Program 7",
    "program_link": "http://example.org/programs/sample-program-7",
    "created_at_string": "09/23/2015",
    "catalog_requested": "No",
    "phone_call_requested": "No",
    "phone_number": "",
    "lead_type": "Application"
  }
]

Getting a list of leads with pagination

Endpoint

GET api/leads

Parameters

Name Description
created_after Date filter; return all results created after this date
created_before Date filter; return all results created before this date
program_id Program filter; return all results with this program id
offset Offset filter; return results starting from offset
limit Limit filter; return only a specific number of results; default 20

Request

Route

GET api/leads?limit=4&offset=1

Headers

X-A101-Date: Wed, 23 Sep 2015 17:43:56 GMT
X-A101-User: sample-provider-7
X-A101-Auth: rKAcyZW6sNgrvGI749/7LMVpcFE=
Message: GETapi/leads?limit=4&offset=1/sample-provider-7Wed, 23 Sep 2015 17:43:56 GMT
Host: example.org
Cookie:

Query Parameters

limit=4
offset=1

Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-UA-Compatible: IE=Edge,chrome=1
ETag: "fdc8714dfe4240f03bbcf3785042ebff"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 3ccf065e8994fef192b3cdfefe511752
X-Runtime: 0.018087
Content-Length: 1640

Body

[
  {
    "id": 14,
    "email": "Sample Lead Email 14",
    "name": "Sample Lead Name 14",
    "university": "Sample University 14",
    "comment": null,
    "address": "",
    "study_period": "Sample Study Period 14",
    "program_id": 8,
    "program_name": "Sample Program 8",
    "program_link": "http://example.org/programs/sample-program-8",
    "created_at_string": "09/23/2015",
    "catalog_requested": "No",
    "phone_call_requested": "No",
    "phone_number": "",
    "lead_type": "Info"
  },
  {
    "id": 15,
    "email": "Sample Lead Email 15",
    "name": "Sample Lead Name 15",
    "university": "Sample University 15",
    "comment": null,
    "address": "",
    "study_period": "Sample Study Period 15",
    "program_id": 8,
    "program_name": "Sample Program 8",
    "program_link": "http://example.org/programs/sample-program-8",
    "created_at_string": "09/23/2015",
    "catalog_requested": "No",
    "phone_call_requested": "No",
    "phone_number": "",
    "lead_type": "Info"
  },
  {
    "id": 16,
    "email": "Sample Lead Email 16",
    "name": "Sample Lead Name 16",
    "university": "Sample University 16",
    "comment": null,
    "address": "",
    "study_period": "Sample Study Period 16",
    "program_id": 8,
    "program_name": "Sample Program 8",
    "program_link": "http://example.org/programs/sample-program-8",
    "created_at_string": "09/23/2015",
    "catalog_requested": "No",
    "phone_call_requested": "No",
    "phone_number": "",
    "lead_type": "Info"
  },
  {
    "id": 17,
    "email": "Sample Lead Email 17",
    "name": "Sample Lead Name 17",
    "university": "Sample University 17",
    "comment": null,
    "address": "",
    "study_period": "Sample Study Period 17",
    "program_id": 8,
    "program_name": "Sample Program 8",
    "program_link": "http://example.org/programs/sample-program-8",
    "created_at_string": "09/23/2015",
    "catalog_requested": "No",
    "phone_call_requested": "No",
    "phone_number": "",
    "lead_type": "Application"
  }
]

Getting a specific lead

Endpoint

GET api/leads/:id

Request

Route

GET api/leads/20

Headers

X-A101-Date: Wed, 23 Sep 2015 17:43:57 GMT
X-A101-User: sample-provider-9
X-A101-Auth: +o3ZUAD+zj9hTkPyT9/UpxoTnPA=
Message: GETapi/leads/20/sample-provider-9Wed, 23 Sep 2015 17:43:57 GMT
Host: example.org
Cookie:

Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-UA-Compatible: IE=Edge,chrome=1
ETag: "9f0cb8331fa1a414e072875e075c172e"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: a88cec04a7ad16c4ba58df9101d6f2e0
X-Runtime: 0.008603
Content-Length: 412

Body

[
  {
    "id": 20,
    "email": "Sample Lead Email 20",
    "name": "Sample Lead Name 20",
    "university": "Sample University 20",
    "comment": null,
    "address": "",
    "study_period": "Sample Study Period 20",
    "program_id": 10,
    "program_name": "Sample Program 10",
    "program_link": "http://example.org/programs/sample-program-10",
    "created_at_string": "09/23/2015",
    "catalog_requested": "No",
    "phone_call_requested": "No",
    "phone_number": "",
    "lead_type": "Info"
  }
]

ReviewAnswers

Getting the list of answers

Endpoint

GET api/reviews/:id/answers

Request

Route

GET api/reviews/1/answers

Headers

X-A101-Date: Wed, 23 Sep 2015 17:43:58 GMT
X-A101-User: sample-provider-11
X-A101-Auth: iTIccyzREjPnqqJfcR8h4O/0sWI=
Message: GETapi/reviews/1/answers/sample-provider-11Wed, 23 Sep 2015 17:43:58 GMT
Host: example.org
Cookie:

Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-UA-Compatible: IE=Edge,chrome=1
ETag: "d751713988987e9331980363e24189ce"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 75712880b2a9c2df68c4709641f13b84
X-Runtime: 0.013602
Content-Length: 2

Body

[

]

Reviews

Getting a list of reviews

Endpoint

GET api/reviews

Parameters

Name Description
created_after Date filter; return all results created after this date
created_before Date filter; return all results created before this date
program_id Program filter; return all results with this program id
offset Offset filter; return results starting from offset
limit Limit filter; return only a specific number of results; default 20

Request

Route

GET api/reviews

Headers

X-A101-Date: Wed, 23 Sep 2015 17:43:58 GMT
X-A101-User: sample-provider-12
X-A101-Auth: Oab2Km4cUrU+h9KGyPXseztlTRk=
Message: GETapi/reviews/sample-provider-12Wed, 23 Sep 2015 17:43:58 GMT
Host: example.org
Cookie:

Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-UA-Compatible: IE=Edge,chrome=1
ETag: "42c4a897548f8c785171748c49c6f6c2"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 68185ca976120a3003025920aaea4100
X-Runtime: 0.019778
Content-Length: 334

Body

[
  {
    "id": 2,
    "university_name": "Sample University 2",
    "title": "Sample Review 2",
    "start_date": null,
    "end_date": null,
    "return_again": null,
    "knowledge_gained": null,
    "program_id": 13,
    "program_name": "Sample Program 13",
    "program_link": "http://example.org/programs/sample-program-13",
    "created_at_string": "09/23/2015",
    "rating": 4.5,
    "admin_rating": null
  }
]

Getting a list of reviews filtered by date

Endpoint

GET api/reviews

Parameters

Name Description
created_after Date filter; return all results created after this date
created_before Date filter; return all results created before this date
program_id Program filter; return all results with this program id
offset Offset filter; return results starting from offset
limit Limit filter; return only a specific number of results; default 20

Request

Route

GET api/reviews?created_after=2015-08-23&created_before=2015-08-25

Headers

X-A101-Date: Wed, 23 Sep 2015 17:43:59 GMT
X-A101-User: sample-provider-13
X-A101-Auth: 6G2nItO+r3CcoxxU7HIGyFuJOx0=
Message: GETapi/reviews?created_after=2015-08-23&created_before=2015-08-25/sample-provider-13Wed, 23 Sep 2015 17:43:59 GMT
Host: example.org
Cookie:

Query Parameters

created_after=2015-08-23
created_before=2015-08-25

Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-UA-Compatible: IE=Edge,chrome=1
ETag: "e58c5b1c291ce0d76c39cd3f53cd361d"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: a9276479c8ccf9aaf49974d8d9090c5d
X-Runtime: 0.013384
Content-Length: 334

Body

[
  {
    "id": 4,
    "university_name": "Sample University 4",
    "title": "Sample Review 4",
    "start_date": null,
    "end_date": null,
    "return_again": null,
    "knowledge_gained": null,
    "program_id": 14,
    "program_name": "Sample Program 14",
    "program_link": "http://example.org/programs/sample-program-14",
    "created_at_string": "08/24/2015",
    "rating": 4.5,
    "admin_rating": null
  }
]

Getting a list of reviews filtered by program

Endpoint

GET api/reviews

Parameters

Name Description
created_after Date filter; return all results created after this date
created_before Date filter; return all results created before this date
program_id Program filter; return all results with this program id
offset Offset filter; return results starting from offset
limit Limit filter; return only a specific number of results; default 20

Request

Route

GET api/reviews?program_id=16

Headers

X-A101-Date: Wed, 23 Sep 2015 17:43:59 GMT
X-A101-User: sample-provider-14
X-A101-Auth: IdfV7LqUPxQOf7S6hEw8d/cuD04=
Message: GETapi/reviews?program_id=16/sample-provider-14Wed, 23 Sep 2015 17:43:59 GMT
Host: example.org
Cookie:

Query Parameters

program_id=16

Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-UA-Compatible: IE=Edge,chrome=1
ETag: "f3939a201bb69442852c459232475081"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 5f821ad52ba858eb5d0e06bb9ddbe0b5
X-Runtime: 0.010611
Content-Length: 334

Body

[
  {
    "id": 6,
    "university_name": "Sample University 6",
    "title": "Sample Review 6",
    "start_date": null,
    "end_date": null,
    "return_again": null,
    "knowledge_gained": null,
    "program_id": 16,
    "program_name": "Sample Program 16",
    "program_link": "http://example.org/programs/sample-program-16",
    "created_at_string": "09/23/2015",
    "rating": 4.5,
    "admin_rating": null
  }
]

Getting a list of reviews with pagination

Endpoint

GET api/reviews

Parameters

Name Description
created_after Date filter; return all results created after this date
created_before Date filter; return all results created before this date
program_id Program filter; return all results with this program id
offset Offset filter; return results starting from offset
limit Limit filter; return only a specific number of results; default 20

Request

Route

GET api/reviews?limit=3&offset=1

Headers

X-A101-Date: Wed, 23 Sep 2015 17:44:00 GMT
X-A101-User: sample-provider-15
X-A101-Auth: uuV/TzLzbWoNciVCVHhPn9MXpUw=
Message: GETapi/reviews?limit=3&offset=1/sample-provider-15Wed, 23 Sep 2015 17:44:00 GMT
Host: example.org
Cookie:

Query Parameters

limit=3
offset=1

Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-UA-Compatible: IE=Edge,chrome=1
ETag: "8666ea8fefdce2de77648ac65b26f401"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: cf7932b04666167d2c82449a0cdeed1e
X-Runtime: 0.013604
Content-Length: 1003

Body

[
  {
    "id": 8,
    "university_name": "Sample University 8",
    "title": "Sample Review 8",
    "start_date": null,
    "end_date": null,
    "return_again": null,
    "knowledge_gained": null,
    "program_id": 17,
    "program_name": "Sample Program 17",
    "program_link": "http://example.org/programs/sample-program-17",
    "created_at_string": "09/23/2015",
    "rating": 4.5,
    "admin_rating": null
  },
  {
    "id": 9,
    "university_name": "Sample University 9",
    "title": "Sample Review 9",
    "start_date": null,
    "end_date": null,
    "return_again": null,
    "knowledge_gained": null,
    "program_id": 17,
    "program_name": "Sample Program 17",
    "program_link": "http://example.org/programs/sample-program-17",
    "created_at_string": "09/23/2015",
    "rating": 4.5,
    "admin_rating": null
  },
  {
    "id": 10,
    "university_name": "Sample University 10",
    "title": "Sample Review 10",
    "start_date": null,
    "end_date": null,
    "return_again": null,
    "knowledge_gained": null,
    "program_id": 17,
    "program_name": "Sample Program 17",
    "program_link": "http://example.org/programs/sample-program-17",
    "created_at_string": "09/23/2015",
    "rating": 4.5,
    "admin_rating": null
  }
]