Students
Authentication required
Successful authentication provides the developer with access to the Student data for their supervising organisation. The Homestay Network API provides access to Student data in the RESTful approach (GET, POST, PUT, DELETE). All requests must provide the token parameter.
List students
Returns name, address and other basic information for all Students supervised by the organisation.
| Name | Description |
|---|---|
| id | The unique identifier in the AHN database |
| name | The name of the student |
| address | The street address |
| city | The name of the city |
| state | The name of the state |
| country | The name of the country |
| post-code | The postal/zip code |
| student-status | The status of the student's application |
| external-id | The External Id of the student's application |
GET: http://api.homestaynetwork.org/students/?token=xxxxx
Response
<students> <student> ... </student> ... </students>
Get student
Returns the full profile data for an individual student under the supervision of the developer's organisation.
GET: http://api.homestaynetwork.org/students/(student-id)?token=xxxxx
GET: http://api.homestaynetwork.org/students/(external-id)?token=xxxxx
student-id relates to the Id column of the Student model in AHN.
external-id relates to the External_Id column of the Student model in AHN.
Response
<student> ... </student>
Create student
Create a new record for a student in the AHN database. The request must be in the POST format, with Content-Type set to 'text/xml' and the following data parameters must be sent:
In aphabetical order (required in red):
| Model | Parameter | Data Type | Description | Options |
|---|---|---|---|---|
| user | username | string(50) | The username for accessing the system | |
| user | string(150) | The primary email address for the student | ||
| user | family_name | string(80) | The family name of the student | |
| user | given_names | string(80) | The given names of the student | |
| student | address | string(250) | The street address and suburb (excluding city, state) | |
| student | bio | string(1000) | Brief biography (about me) text for the student | |
| student | campus-id | integer | ID representing the campus the student will be attending. Not to be mistaken for Institution | Campuses |
| student | city | string(150) | Name of the student's home city | |
| student | committed-of-crime | boolean | Whether the student has been convicted of a crime | True/False |
| student | country-id | integer | Id of the student's home country | Countries |
| student | course-date-end | date | The date the student's course will end | |
| student | course-date-start | date | The date the student's course will start | |
| student | course-id | integer | ID of the course a student will be studying | Courses |
| student | crime-details | string(250) | Details of any crimes the student has been convicted of | |
| student | dietary-needs | string(250) | Details of the student's dietary needs | |
| student | dob | date | Student's Date of Birth | |
| student | emergency-contact | string(40) | The name of the student's emergency contact | |
| student | emergency-contact-phone | string(30) | The contact phone number for the student's emergency contact | |
| student | emergency-contact-relationship | string(100) | The relationship of student's emergency contact to the student | |
| student | english-level | integer | The student's level of English |
1 = Beginner 2 = Pre-intermediate 3 = Intermediate 4 = Upper-intermediate 5 = Advanced |
| student | external-id | string(20) | The unique identifier of the student (external to AHN) | |
| student | fax | string(20) | The student's facsimile (fax) number | |
| student | foods-not-eaten | string(255) | Description of foods the student does NOT eat | |
| student | gender | string(1) | The student's gender |
m = Male f = Female |
| student | guardian-contact-details | string(500) | The full contact details of the student's guardian | |
| student | guardian-name | string(50) | The name of the student's guardian | |
| student | has-ielts | boolean | Whether the student has an IELTS score | True/False |
| student | hobbies-interest | string(255) | Description of the student's hobbies/interests | |
| student | home-language-id | integer | The ID of the student's home language | Languages |
| student | homestay-start-date | date | The date for the student's intended homestay start | |
| student | host-service-id | integer | The student's intended level of service | Host Services |
| student | ielts-score | decimal | The student's IELTS score | |
| student | legal-guardian-contact-details | string(255) | The contact details of the student's legal guardian | |
| student | legal-guardian-name | string(50) | The name of the student's legal guardian | |
| student | live-with-children | boolean | Whether the student will live with children | True/False |
| student | live-with-pets | boolean | Whether the student will live with pets | True/False |
| student | medical-conditions | string(255) | Description of the student's medical conditions (if any) | |
| student | medication | string(255) | Description of the student's medication requirements | |
| student | nationality-country-id | integer | ID of the student's country of nationality | Countries |
| student | other-institution | string(50) | The name of the student's institution. Only required if campus-id is not available | |
| student | pet-details | integer | The host's second language | Languages |
| student | phone-home | string(20) | The student's home phone number | |
| student | phone-mobile | string(20) | The student's mobile phone number | |
| student | post-code | string(8) | The student's home post code | |
| student | preferred-name | string(50) | The student's preferred (English) name | |
| student | product-id | integer | The product that the student is assigned to | Products |
| student | require-internet-access | boolean | Whether the student requires internet access | True/False |
| student | requires-transport | boolean | Whether the student requires transport to/from their institution. | |
| student | smoker | boolean | Whether the student smokes | True/False |
| student | special-needs | string(255) | Description of any special needs of the student | |
| student | vegetarian | boolean | Whether the student is vegetarian | True/False |
| student | will-live-with-smoker | boolean | Whether the student will live a smoker | True/False |
| student | agent_office_ids | array | An array of Agent Office Ids linked to this student | Agents |
POST: http://api.homestaynetwork.org/students/?token=xxxxx
The student data may be posted with the request as XML in the following format:
<request> <user> <given_names>Joe</given_names> <family_name>Bloggs</family_name> <email>joe@mail.com</email> ... </user> <student> <address>25 Foobar St</address> <city>Beijing</city> <country_id>3</country_id> ... <agent_office_ids>13</agent_office_ids> <agent_office_ids>205</agent_office_ids> ... </student> </request>
Response
<response> <status>201</status> <message>xxx</message> </response>
Note: The 'message' refers to the Id of the new student record.