Information for Developers

Childminder allows developers to enforce age limits on their sites and thus protect children using interactive resources on those sites such as chat rooms and forums. This is because children are safer using these features if adults can be prevented from using them.

We use the fact that most site that require a login also require e-mail addresses to be validated by sending a message to the users entered e-mail address. Our system allows you to then associate that e-mail address with the user’s date of birth and thereby enforce a maximum age policy on your site.

Childminder maintains a database of children’s dates of birth correlated to their e-mail addresses. To benefit from this system you need to do the following:

  1. Enrol in the Childminder system.
  2. Add the given code to your login system
  3. Ensure that your login system is validating e-mail addresses
  4. Test your system making sure that a negative response results in a failed login response to the user.

Please note that you are responsible for making sure that the code provided to you works as intended on your site and for confirming that a ‘not validated’ response from Childminder prevents the user from loging in.

Methodology

Childminder is written in PHP and is easiest to implement if your site uses PHP too but can be used with any platform simply by calling a url that we give you and parsing the file that we send back. The url will typically look like this:

http://www.childminder.com/check/?email=f1c675fda782e9fe3af3ac78f2087c24&responseformat=serializedphp&threshhold-18

As you can see the url contains your formatting options and the md5 of the e-mail address you are trying to age-validate.

The following parameters are available:

  • email: the md5 of the e-mail address to be age-validated (md5 string)
  • threshhold: the age limit (integer; default: 18)
  • validateddate: the date on which your system validated this e-mail address (yyyy-mm-dd)
  • responseformat: the format in which you want the data returned (serializedphp | xml; default: xml)
  • condition: whether the users age must be under or over the threshold (under | over; default: under)
  • hash: the hashing scheme used to encode the e-mail address (md5; default: md5)
  • key: the API key given to you when you enrol your site (unique for each domain) (API key string)

You can control the format of the file sent to you which is available in the following formats:

  • PHP serialized array
  • XML

PHP serialized array

When the serialized arary is returned just use the PHP unserialize function to convert it into an array again. Here’s what it will look like:

Array
(
    [validated] =>
    [email] => f1c675fda782e9fe3af3ac78f2087c24
    [errornumber] => 0
    [errorname] =>
    [errordesc] =>
    [comment] =>
)
  • Validated: contains binary true false indicating whether the age-validation passed
  • email: confirmation of the email that was checked (useful for batch verification)
  • errornumber: an integer referring to an error returned
  • errorname: a shorthand string reference to the error
  • errordesc: a longhand string reference to the error
  • comment: this ensures that we can send you messages even if your e-mail address is no-longer working. You should log comments returned in this parameter and check the contents at least once a month.

XML document

<response>
    <validated>false<validated>
    <email]>f1c675fda782e9fe3af3ac78f2087c24<email]>
    <errornumber>0<errornumber>
    <errorname><errorname>
    <errordesc><errordesc>
    <comment><comment>
<response>

Parameters are the same as for the PHP serialized array with one exception: the <validated> binary state is spelled out as a string.

Errors returned

The following errors are returned. Please note that the errorname and errordesc parameters are provided for your convenience but do not interrogate them to ascertain the nature of the error as they may change in the future. Use the errornumber instead wich will remain fixed for the life of this service. If an error occurs the validated parameter will revert to false but this does not mean that the validation process was carried out.

0: No Error; No Error was returned: check the validated parameter for the result

1: Not Found: the e-mail address given was not found in our database

2: Invalid e-mail: the encoded e-mail address is not a valid hash

3: threshold invalid: The threshold is not a valid integer

4: Invalid validateddate: The date given is not in a readable format

5: Old validatedate: The validateddate indicates that you did not validate the e-mail address within the required period

6: Invalid responseformat: The responseformat is not one we support (serializedphp,XML)

7: Invalid hash: the hash declaration is not one we support (md5)

8: No key: No API key is provided

9: Invalid key: The key provided is not valid for this domain

—