Lamplight data in API

Introduction

The data in API is what you use to send data to the Lamplight servers. Lamplight offers a fairly simple Query interface to request data, which is returned in json format (although we may add alternatives in due course).

You will need an API key and access parameters from Lamplight to access data: these are available to system administrators through the admin menu within Lamplight.

The core API documentation can be found here.

Contents

  1. Conventions / styles used in this document
  2. Constructing the request
  3. Authentication credentials
  4. Other parameters used in all requests
  5. Data returned - general
  6. Adding to work records
    1. Attend work records
  7. Referral
    1. Creating referral records
  8. People (version 1.2)
    1. Adding profiles for people
    2. Updating profiles for people
    3. Adding profiles for organisations
    4. Updating profiles for organisations
  9. Error codes

Conventions/styles in this document

After the introductory sections, the details of how to construct the query are split into sections by type of record: work, organisation, people and workarea. Each section is of the following form:

type/dowhat

A brief description of what this does.

URI

The base uri for the request is shown:

https://lamplight.online/api/type/dowhat

As discussed below, type will be something like work, and dowhat something like attend

Parameters

In the documentation below, parameters highlighted in

red
Type are required parameters
black
Type are not required. Type, in green, is String | Array | Int etc.

Returns

A list of the fields returned, plus any additional information

id
Type A description of the return value for this field.
name
Type A second field in the returned record. As above, type indicates the datatype, although it is likely that json encoding will convert all values to strings. If this is important, you may need to cast values to the proper type.

So on to the real stuff...

Constructing the request

The base uri to use is https://lamplight.online/api. To this uri, you need to append two parameters, separated by a forward slash (/), which describe what kind of data you want, and the type of request: https://lamplight.online/api/what/dowhat.

Here, what must be work or referral (currently)

and dowhat must be attend or add (currently).

Requests may use GET or POST to provide parameters, should use UTF-8 character encoding, and all parameters should be properly encoded. However, to be corrent you should use POST requests (and the Lamplight_Client does so automatically).

Credentials

There are three access credentials that are required: your Lamplight ID, a project ID, and your customer API key. These must be provided with the request, either as GET or POST parameters. If you append them as a query string, they must appear after the what and howmany parameters described above.

The parameter names are:

Parameters - credentials

lampid
Int Your id - available through the admin menu of Lamplight
project
Int Project id - available through the admin menu of Lamplight. Even if you only have one project this will be needed.
key
String API key - available through the admin menu of Lamplight

All of these are required. An error response will be returned if these are omitted or incorrect

Other parameters used in all requests

There is only one other required parameter, and one optional:

Parameters - other

format
String The format of results: currently the only value available is json
callback
String Your results will be wrapped with the callback({/*data*/}) you specify. This may be used in javascript implementations to enable you to process the data once it is added to the page.

Note that using javascript means that you will inevitably make your access credentials public; in many cases this will not be desirable. We recommend that you set up a simple server proxy if you wish to use javascript, that can append access credentials at the server, and pass returned data straight through.

In some cases you can use custom fields as parameters (for example, to search by 'services offered'. In these cases, field names should use the underscore character instead of spaces, and be lower case.

Data returned

Currently the only format available is json. A successful request will return an object with two keys: data and meta. data will generally hold just an id value for confirmation, and meta is currently unused by the datain module but has been retained for future use. For example: 

{
 data: 12345,
 meta:''
}

(White space added for readability). If there is an error, the object returned will be of the form:

{
 error: 1001,
 msg: "An English explanation of what the error code (1001 in this example) means"
}

Adding attendees to work records

You may add attendees to published work records through the API, providing the correct permissions have been set in Lamplight.

work/attend

URI

The uri to add someone as attending a work records is

https://lamplight.online/api/work/attend/

Parameters

id
Int | String ID of the work record, or a comma-separated list of IDs, returned by a request to work/some or work/one.
attendee
String The email address of the person wishing to attend.

Returns

Each record returned will have the following fields:

id
IntThe Lamplight ID of the work record
attend
BooleanWhether they were able to be added OK

Example

An example showing how to add to multiple work records is available here. From that example you can also see how to add to individual records.

Creating referrals

You may create referrals through the API, providing the correct permissions have been set in Lamplight.

referral/add

URI

The uri to create a new referral is

https://lamplight.online/api/referral/add/

Parameters

attendee
String Email of the the person being referred
referral_reason
String Their reason for the referral - will be entered in the 'referral reason' field within Lamplight. Plain text only - no HTML is allowed.
date_from
String YYYY-mm-dd date of the referral - defaults to current date if none passed.
workareaid
Int The workarea to use on the referral. A default can be set within Lamplight if necessary: this will over-write the default if provided.

You can also set custom referral fields to be added, where they have been set to be updatable in the system admin section. To add custom field values, send the field name (with spaces replaced by underscores) and valid data.

Name_of_custom_field
mixedValue to add. Options should be as-is (not with spaces replaced with underscores)

Returns

Each record returned will have the following fields:

id
IntThe Lamplight ID of the work record

Example

An example showing how to add a referral is available here.

Profiles for people/organisations

From version 1.2 of the API, you may create and update profiles for people or organisations through the API, providing the correct permissions have been set in Lamplight.

Profiles added in Lamplight may be placed in a 'holding list' and will need to be confirmed before they become available for use in Lamplight. This is configurable within the admin section of Lamplight.

people/add

URI

The uri to create a new profile for a person is

https://lamplight.online/api/people/add/

Requests to people/add MUST be POSTed. Trying to add using GET will return an error.

Parameters

role is the only required parameter. All other parameters are optional (although if you do not pass any data, Lamplight will return an error). All parameters need to be enabled within Lamplight (in the admin section) before they will be accepted by the API. Other parameters match the data that may be requested through the API. Invalid data will be rejected.

role
String The role of the person to be created. The possible values are the same as those available when requesting details of people - one of user, staff, contact or funder
first_name
String Their first name.
surname
String Their surname.
address_line_1
String Their address line 1.
address_line_2
String Their address line 2.
address_line_3
String Their address line 3.
address_line_4
String Their address line 4.
address_line_5
String Their address line 5.
postcode
String Their postcode
mobile
String Their mobile number
phone
String Their phone number
email
String Their email
web
String Their website address

You can also add custom fields, where they have been enabled for updating within Lamplight. The format and approach is the same as when requesting these fields. The field name should be the text of the field, in all lower case, with underscores '_' replacing any spaces. The value should be valid for the field. If the field has options (i.e. a select, checkbox, radio etc) the value should be the text value of the option. For example:

gender
Male A custom field that may be altered through the API.
date_of_birth
1982-04-16 Another custom field that may be altered through the API.

Returns

If the record is added successfully, the response will be an object with a property data, the value of which will be the ID of the new profile. If there was an error the object will have properties error and msg

data
IntThe Lamplight ID of the profile

Example

An example showing how to add a profile is available here.

people/update

URI

The uri to update an existing profile for a person is

https://lamplight.online/api/people/update/

Requests to people/update MUST be POSTed. Trying to update using GET will return an error.

Parameters

role and id are the only required parameters. All other parameters are optional (although if you do not pass any data, Lamplight will return an error). All parameters need to be enabled within Lamplight for updating (in the admin section) before they will be accepted by the API. Other parameters match the data that may be requested through the API. Invalid data will be rejected.

role
String The role of the person to be created. The possible values are the same as those available when requesting details of people - one of user, staff, contact or funder
id
Int The ID of the person to be created.
first_name
String Their first name.
surname
String Their surname.
address_line_1
String Their address line 1.
address_line_2
String Their address line 2.
address_line_3
String Their address line 3.
address_line_4
String Their address line 4.
address_line_5
String Their address line 5.
postcode
String Their postcode
mobile
String Their mobile number
phone
String Their phone number
email
String Their email
web
String Their website address

You can also add custom fields, where they have been enabled for updating within Lamplight. The format and approach is the same as when requesting these fields. The field name should be the text of the field, in all lower case, with underscores '_' replacing any spaces. The value should be valid for the field. If the field has options (i.e. a select, checkbox, radio etc) the value should be the text value of the option. For example:

organisation_status
Registered_charity A custom field that may be altered through the API.

Returns

If the record is updated successfully, the response will be an object with a property data, the value of which will be the ID of the new profile. If there was an error the object will have properties error and msg

data
IntThe Lamplight ID of the profile

Example

An example showing how to update a profile is available here.

orgs/add

URI

The uri to add a profile for an organisation is

https://lamplight.online/api/orgs/add/

Requests to orgs/add MUST be POSTed. Trying to add using GET will return an error.

Details for adding organisations is identical to that for people, except that instead of first_name and surname parameters there is a single name parameter.

orgs/update

URI

The uri to update an existing profile for an organisation is

https://lamplight.online/api/orgs/update/

Requests to orgs/update MUST be POSTed. Trying to update using GET will return an error.

Details for updating organisations is identical to that for people, except that instead of first_name and surname parameters there is a single name parameter.

Error messages

If there is an error in your request, the server will return an HTTP 400 code, and the body of the response will contain a json encoded error object. Error codes returned by Lamplight start 10xx.

1020
"The data in module for work records is not enabled". The datain functionality is not available with your current Lamplight subscription. Please contact us to enable it.
1021
"No valid work record id was passed to attend". The id parameter should be an integer, returned by Lamplight.
1022
"The attendee did not pass a valid identifier". The email address provided is not valid.
1023
"The record may not be added to". Work records in Lamplight need to have the 'allow attendees to be added via the API' checkbox selected.
1024
"The attendee could not be unambiguously identified in the database". This means that they either are not there at at all, or appear more than once. A message will be created within Lamplight for the system administrator, providing details.
1025
"There are no spaces available on the record requested". If set, the maximum number of attendees has been reached and no more people can be added to the record. A message will be created within Lamplight for the system administrator, providing details.
1026
"This attendee is already attending the record requested". They are already listed.
1027
"This type of record (work etc) may not be accessed through the API". You are trying to add someone to a record of a type that has been denied access - your system administrator will need to set this in the datain section of the admin menu.
1040
Referral data provided was not valid
1050
Updating person or organisation data must be POSTed
1051
If you want to update a record you need to provide a valid ID
1052
Do not have permission to update this type of body
1053
This particular profile may not be updated
1054
Do not have permission to add profiles of this type
1055
Data provided to add/update profile was not valid
1056
No valid data found to add/update
1057
There was a problem saving the core name/address fields for the update
1058
There was a problem saving some custom fields: most likely values provided are not valid for the field. Core details (name/address) will have been saved if provided.
9999
Data provided may have been a malicious attack and has not been added. Specifically, POSTed content includes html tags and the request is immediately rejected.

php client

If you are using the php client, it will add a couple of error codes (starting 11xx):

1100
The response could not be parsed as json, but the response status was 200 OK.
1101
A strange error: the server did not return a 200 OK, the response was parsed as json, but did not include an error code and message from the server. Basically, you shouldn't ever see this error.

The php client documentation has more information on retrieving error codes/responses.