School-links and Beep4Business supports CSV uploads for general users (e.g. admins, associates, contacts) via HTTPS API.
You'll need a system that has an integration with SL/B4B, or you'll need to write your own upload integration.
To get credentials (username and password) to use this API, you'll need to submit a ticket to our helpdesk.
API
Endpoint URL (HTTPS only):
https://api.school-links.org.nz/data/uploadCsv
Please note this url is case sensitive
Request Details
Method: POST
Authorisation: HTTPS Basic Authorization
Request Body: form-data
Parameters:
- file (required) - the CSV file to be uploaded in the format specified below. Maximum 5MB
- This must be passed in the form-data format in the request body
Example Request
curl -X POST https://api.school-links.org.nz/data/uploadCsv \ -H "Authorization: Basic dG9wOnNlY3JldA==" \ -H "Content-Type: multipart/form-data" \ -H "file=@/path/to/file.csv"
Response Details
Success Response
Status code: 201
Content:
{
"data": {
"filename": "2023-02-08-14-05-25-api-example-primary.csv",
"cleanupFromPrevious": false
}
}Authentication Error
Status code: 401
Content:
{
"errors": [
{
"status": 401,
"title": "Authentication Error",
"detail": "Requires authentication (empty or incorrect username/password)"
}
]
}Authorisation Error
Status code: 403
Content:
{
"errors": [
{
"status": 401,
"title": "Authorisation Error",
"detail": "Unauthorised (organisation may not be enabled for API access)"
}
]
}Request Error
Status code: 400
Content:
{
"errors": [
{
"status": 401,
"title": "Invalid Payload",
"detail": "Missing or invalid file"
}
]
}
CSV Format
CSVs must be formatted according to RFC 4180 (e.g. enclosing fields containing commas in double quotation marks ""S) and use UTF-8 (without BOM) or ASCII encoding. Note that some fields in SL/B4B support only ASCII characters.
Example CSV files
- Simple file with minimal fields: minimal.csv
- Example file for school alumni: school-alumni.csv
- Example file for business with two offices: office-business.csv
Format Details
- Encodings supported: UTF-8 (without BOM) or ASCII
- The first row of the file must contain a header row that defines column names/types.
- For each column, the header row value should be a string consisting of one of the supported column names listed in the leftmost column of the table below
- Column names must be unique within a file (e.g. if "email" appears in the header row more than once, we will import only one of these two columns)
- Subsequent rows must contain data that is compatible with the column definitions in the header row (e.g. "email" column data must contain valid email addresses
Available header row column names, the data fields they map to in School-links / Beep4Business, and the data type requirements are listed in the table below.
Some column names have multiple aliases, such as "email" and "email address", which both map to the same data field in SL/B4B. If multiple columns in your CSV map to the same SL/B4B data field, we will use only one of the columns for importing.
Available header names and their mappings
| Column name(s) in CSV header row | Data field mapped in SL/B4B | Description | Data Type | Required? |
|---|---|---|---|---|
| smsid | smsid | Customer's unique identifier for this person | ASCII string up to 128 characters long Must be unique across all person records at your organisation | No |
| type | (role type) | SL/B4B role type of person in this record (e.g. "staff" or "associate") | One of the following strings:
| Yes |
| first name first | first name | Person's first name | UTF-8 string (<= 64 characters) | Yes (or full name) |
| last name last | last name | Person's last name | UTF-8 string (<= 64 characters) | Yes (or full name) |
| full name | full name | Person's full name (as an alternate to first + last) | UTF-8 string (<= 384 characters) | No (unless no first + last) |
| middle names | middle names | Person's middle name(s) | UTF-8 string (<= 256 characters) | No |
| title | title | Person's title | UTF-8 string (<= 8 characters) | No |
| gender | gender | Person's gender | Gender string ("f" / "m" / "male" / "female") | No |
| dob.yyyymmdd | date of birth | Person's date of birth | Date string in YYYY-MM-DD format e.g. "2023-12-25" | No |
| dob.ddmmyyyy | date of birth | Person's date of birth | Date string in DD-MM-YYYY format e.g. "25-12-2023" | No |
| email email address email_address | Person's email address | Valid email address string | No | |
| mobile mobile phone mobile_phone cell cellphone | mobile | Person's mobile phone | Mobile phone string in either:
Spaces and other characters are stripped automatically. | No |
| room location office teacher.room staff.room staff.location staff.office | Teachers / Staff only room (School-links) location (B4B) | Metadata field semantically intended for a human-readable location | Text string (<= 256 characters) | No |
| subject department division teacher.subject staff.department staff.division staff.subject staff.role | Teachers / Staff only subject (SL) role (B4B) | Teacher's primary subject (SL) Staff metadata (B4B) | Text string (<= 256 characters) | No |
| teacher.code teacher.staffcode staff.code staffcode | Teachers / Staff only staffCode | Teacher's code e.g. MGO (SL) Staff code or identifier (B4B) | Text string (<= 128 characters) | No |
| association associate.association | Associates only association | Metadata field semantically intended to show how a person is associated with the organisation | Text string (<= 64 characters) | No |
| contacttype contact.contactType contactgroup | Contacts only contactType | Metadata field semantically intended to group other contacts into categories | Text string (<= 256 characters) | No |