Back to index
Developer documentation

User API

The user API allows you to create, read, update and delete users from your account. It also has specialized methods to log in a browser while creating or updating a user object at the same time. If your site has its own login system and database with user information you can use this API to sync it with the SuperSaaS user database. This allows you to provide your users with a way to register and log in only once.

The API accepts data as URL parameters, as JSON or as XML, and can return data as either JSON or XML.

There are several options to keep the SuperSaaS database updated using the API calls below. The simplest implementation consists of a single button:

  1. You create a single Book Now button on your site that contains all relevant information for the person that is currently logged in on your site
  2. When the person clicks the button, his information is posted to the SuperSaaS API, along with a checksum to prevent tampering
  3. If it is the first time the person is sent to SuperSaaS, a new user account is created with the supplied information. Otherwise, his existing information is updated if it changed
  4. The person will be automatically logged in to SuperSaaS and redirected to your schedule

This way of working allows you to only sync the subset of your users who are actively using SuperSaaS and avoids the need for an initial full sync. In theory, there’s a small risk of the databases getting out of sync if you only implement the button. This can happen if the user’s information is changed on your site and he then returns to SuperSaaS without clicking the button, for example because he has bookmarked the page. If this is an issue, you could implement the server-side API calls detailed below to send the updated information from your server directly to SuperSaaS each time user information changes on your site. The API calls have options to make them silently fail on non-existing users, so you can still keep only the subset of active users in SuperSaaS.

An alternative to the procedure above is to do an initial sync of your entire user database (manually or automated), and on each update to your own database send an API call from your server to keep SuperSaaS in sync. You can then create a simple link to log them in automatically and redirect them to your schedule.

You could also make your own database follow the changes in SuperSaaS, but in the following discussion we assume that you want to make your own database leading and let SuperSaaS follow that. Therefore, you want to prevent people from changing their information in the SuperSaaS database. You will want to make the following settings:

  • On the Access Control page, under the heading Who can create a login name?, select Log in and registration managed on your site.
  • Uncheck the option Use email address as login name, unless your site uses email addresses as login name.
  • Under What information should the user enter when creating a login name, select fields as appropriate. You can switch off Password. Although you can synchronize passwords too, there is no need since login takes place elsewhere.
  • You will also want to check the option Prevent users from updating their own information so your own database stays in the lead.
  • On the Layout Settings page make sure Your URL is filled out. Should people somehow end up at SuperSaaS without logging in at your site first, they will be sent there.

Create and Login

The easiest way to implement single sign-on is to provide all the needed information when you send the user over from your site. SuperSaaS will check if the user already exists and update or create the database record as appropriate.

This is an illustrative HTML snippet that you would put on your site to make this work:
<form method="post" action="https://www.supersaas.com/api/users">
  <input type="hidden" name="account" value="Your_account_name"/>
  <input type="hidden" name="id" value="1234fk"/> <!-- A unique key to identify the user. See below -->
  <input type="hidden" name="user[name]" value="joe@client.com"/> <!-- Any string. Needs to be unique -->
  <input type="hidden" name="user[phone]" value="123-456-789"/>
	<!-- values for other fields, see the bottom of the page for a list -->
	<!-- you can add and remove fields in the "Access Control" screen -->
  ...
  <input type="hidden" name="checksum" value="A4E67...DFEF"/> <!-- 32 digit MD5 Hash, see below -->
  <input type="hidden" name="after" value="schedule_name"/> <!-- where you send your user after sign on -->
  <input type="submit" value="Book now"/>
</form>

To see this snippet filled in with appropriate values for your account, see this example. If you happen to use Joomla, Drupal or WordPress as a content management system, then you can download a ready-made Joomla module, Drupal module or WordPress plugin.

Authentication for booking widgets

Via the widget configuration page you add schedule that appears integrated into your site, either inside a frame or as a button that shows it when clicked. If your users are already logged into your own website, it’s possible to automatically log them into the widget as well so they do not need to log in a second time.

After configuring the widget, an HTML snippet is shown at the bottom of the widget configuration page and can be copied into your site’s HTML. By adding another script tag on the page above the widget snippet, you can set the following JavaScript globals to be used by the widget for built-in API authentication:

Variable NameComment
supersaas_api_user_idRequiredA unique key to identify the user. See below.
Note: This variable puts the widget in Create and Login mode. For login-only, see below.
supersaas_api_userRequiredA user object containing at least the property name, but also optionally any of the following:
{"name":"my_username","full_name":"","mobile":"","address":""}
See this example for a list of all fields relevant to your account.
supersaas_api_checksumRequired32 digit MD5 Hash, see the authentication page.

Your API authentication configuration script tag should look similar to this:

<script>
  // This is an example, replace with generated values
  var supersaas_api_user_id = "1234fk";
  var supersaas_api_user = {"name":"my_username","full_name":"","phone":"","address":""};
  var supersaas_api_checksum = "1a79a4d60de6718e8e5b326e338ae533";
</script>

So if you generate the above script via your site’s server-side programming language with real data from the currently logged-in user, then their account will be automatically created or updated as soon as the widget loads. The created or updated user will then be automatically logged in inside the widget as well.

Three options for the Database Key

To be able to keep track of changes both databases need to use the same unique key. This ID needs to be sent along with each transaction to identify the record that needs to be modified. To facilitate easy implementation, you have three options to choose from:

  1. You can provide your own unique 32-bit number. Typically, the index key of your own user database is a good value to use. You indicate you are providing your own key by post-fixing the ID with the letters ‘fk’ (foreign key).
  2. You can use the internal SuperSaaS user ID, which is also a 32-bit number. When you create a new record, you have to retrieve and store that ID in your own database and subsequently send it along when you update that record.
  3. You can use the person’s name as the key or any other unique 50-byte string that does not start with a number. It is not a good idea to use something as a key if the person is allowed to change this value, since he would be disconnected from his bookings each time he changes it. If your own database key is something other than a 32-bit number, you could repurpose this field to store your key.

Authentication

Please first refer to the Authentication Page.

There is no need to provide the user’s password this way since the form is already authenticated with the checksum. You can send a user password, and it will be stored, but it is better not to do so because it would be visible in the source of the web page. If the record was successfully created or updated, the user is redirected to the URL contained in the after parameter. You can provide additional values in this URL to ensure the user ends up at a predetermined date and view.

If you only provide the sign-on button and stop there, then the two databases can get out of sync, which you may or may not find acceptable. For instance, a person can change his information on your site and it won’t be updated until he uses the above button again. Also, a user that you delete from your own database will not be removed from the SuperSaaS database. Usually, the slightly outdated information is no reason for concern because it gets updated on the next visit. However, if you want to keep the SuperSaaS in sync you can update the SuperSaaS database from your own server by sending the API calls detailed below each time user information changes on your server. As an aside, the reverse is also possible, you can set a webhook to send a message to your server each time the information changes on SuperSaaS, but it’s often easier to simply disallow the user to make changes to his own information while on the SuperSaaS site.

Log in only (without create)

If you have already managed to get the databases in sync, either manually or with the API calls below, you can log the user in with the following link (POST or GET), using the same parameters as to the call above:
Try it out
https://www.supersaas.com/api/login?account=&after=Schedule_url&user[name]=user@client.com&checksum=A4E67...DFEF
This tutorial can display code snippets relevant to your account if you log in
This tutorial can display code snippets relevant to your account if you generate an API Key at the bottom of the Account Info page by clicking the Generate button.

If the request contains an “Origin” header then the server will add appropriate CORS headers. This will allow the request to be sent from an AJAX call inside a browser. It’s highly recommended sending any request from the browser via an SSL encrypted (https) connection.

Integration with booking widgets (without automatic account creation)

With the databases in sync, if you use on of our scheduling widgets on your site, you can add a simple script tag setting the following JavaScript globals with data from your currently logged-in user anywhere on the page before the other widget script tags, and the user will be automatically logged in inside the widget too as soon as it loads:

Variable NameComment
supersaas_api_userRequiredA user object containing only the property name. E.g.:
{"name":"my_username"}
supersaas_api_checksumRequired32 digit MD5 Hash, see the authentication page.

The script tag should look similar to this:

<script>
  // This is an example, replace with generated values
  var supersaas_api_user = {"name":"my_username"};
  var supersaas_api_checksum = "1a79a4d60de6718e8e5b326e338ae533";
</script>

So if you generate the above script via your site’s server-side programming language with real data from the currently logged-in user, then the user will be automatically logged in inside the widget too as soon as it loads.

The Users API

The API to the User database is RESTful. It can be consumed by properly written libraries such as Ruby on Rails’ Active Resource. For each call you need to authenticate with the server by either adding your account name and api_key as URL parameters or by using HTTP Basic Authentication. For example: https://supersaas.com/api/users?account=YourName&api_key=api_key. You can also use the MD5 checksum method outlined on the authentication page. For additional security you can use SSL.

Create a new user

To create a new user, you need to send an HTTP POST request to /api/users.json. The request should either contain an XMLJSON document describing the new user, or have the fields as URI encoded parameters. See below for the data format.

POST /api/users   (SuperSaaS will assign a key)
POST /api/users/{id}   (You provide your own key in the format 9999fk)

If the record is correctly created the response will be a header with status code 201 Created.

The Location field of the response header will contain the URL that you can use to retrieve the user later, e.g.: Location: https://www.supersaas.com/api/users/1234.xmljson. If you want to find out the SuperSaaS ID (1234) of the created object, you can extract it from this URL.

If the object fails validation, perhaps because of an invalid email address, then status code 422 Unprocessable Entity will be returned, with the body of the response containing the error messages.

When you provide your own key and the key already exists in the database, your call is assumed to be an update instead. To avoid a ‘create’ action from being automatically interpreted as an ‘update’, you can add the parameter duplicate=raise. In that case a status code 422 will be returned instead. Note that if your booking ID contains a period (.), you may need to use the id parameter (/api/users?id={id}) to get it to work correctly.

Data Format

The fields that you can supply are determined by the settings on the Access Control screen. Except for the username, all values are optional and will be set to a default value (usually blank) if not provided.

FieldComment
nameRequiredThe name of the user, max. 50 bytes. If you selected to use email addresses as login names then this has to be an email address.
emailOptionalThe email address of the user. Ignored if you use the email address as login name.
passwordOptionalPassword for the user, if you are using password login
full_name, address, mobile, phoneOptionalIf any of these attributes are present they are stored unchanged as UTF-8 encoded strings
countryOptionalEither not present or a two character ISO 3166-1 country code
timezoneOptionalEither not present or a IANA TZ identifier
field_1, field_2,
super_field
OptionalThe values of the two custom fields and the supervisor field, irrespective of the display label you have given them on the configuration pages.
creditOptionalSets the credit level (default is 0). The format is selected on the Payment Setup screen.
roleOptionalAllowed values are:
3: Regular user (default)
4: Superuser
-1: Blocked user
webhookOptionalIf webhook=true is present it will trigger any webhooks connected to the account.

When reading data the retrieved document will contain the following fields in addition to the ones listed above:
FieldComment
idThe internal ID assigned to this user by SuperSaaS
fkThe ID assigned to this user by you if you supplied a foreign key
created-onThe time this user was created in UTC

Illustrative Usage

This example call will create a new user record in the SuperSaaS user database. The record has database key 567 in your own database:
POST /api/users/567fk.xmljson
You would send your account name and api_key in the header, using HTTP Basic Authentication and send the following body:
<?xml version="1.0"?>
<user>
   <full-name>Full Name</full-name>
   <name>user@example.com</name>
</user>
{
  "full_name": "Full Name",
  "name": "user@example.com"
}

This would return a 201 Created response with an empty body. If you are instead using query parameters, replace dashes with underscores in the field labels and write them as user[field_name]. All values need to be URI encodes as well.

Example code for the same call, this time with query parameters:
Try it out
POST /api/users/567fk.json?account=&password=secret&user[name]=user@client.com&user[password]=secret&user[full_name]=Full%20Name

In the above example we’ve used the MD5 checksum as authentication. This avoids the need to send the api_key in clear text, which can pose a security problem.

Read one user

Try it out
GET /api/users/{id}.json
If the ID is fully numeric it is assumed to be our key, otherwise it is considered to be your key. If the ID is alphanumeric it will be stored in the name field. Alphanumeric IDs can be provided as URI encoded parameters to avoid illegal characters in the URL, like so: /api/users?id=ab%25cd. The response will be a 404 Not Found or 200 OK with the response body a JSONan XML document describing the user.
<user>
   ...
</user>
{
  "id": "123456",
  "name": "example",
  "email": "example@gmail.com",
  ...
}

Read all users

GET /api/users.json
This returns a 200 OK with an XMLJSON document describing all users on your account. By default, the number of records sent is limited to 100, but you can increase this by adding a limit parameter like this /api/users.json?limit=500. If you want to retrieve more than 1000 objects you can split the request into multiple calls, and add an offset parameter to retrieve the subsequent page: /api/users.json?limit=1000&offset=1000
<users>
   <user>
      ...
   </user>
   <user>
      ...
   </user>
</users>
[
  {
    "id": "123456",
    "name": "example",
    "email": "example@gmail.com",
    ...
  },
  {
    "id": "789123",
    "name": "example2",
    "email": "example2@gmail.com",
    ...
  }
]

Show forms

When a form is attached to a user, you can show the form’s data by adding the form=true parameter to the URL. The output will be the same as the Form API.

Update a user

To update a user, you need to send an HTTP PUT request to /api/users, specifying the ID of the user in question. Similar to creating a user, you can either provide an XML document, a JSON document or use URI encoded parameters.

Try it out
PUT /api/users/{id}.json

The system looks for the record with the given ID and updates it. The result will be 200 OK or a 422 Unprocessable Entity with an error document.

In case the record cannot be found, the system assumes you want to do a “create” instead. To avoid automatically creating a new record, you can add the parameter notfound=error or notfound=ignore to return a 404 Not Found or 200 OK respectively.

If you are trying to use a SuperSaaS internal key that doesn’t exist, a 404 Not found status is returned.

If the software you are using does not support sending of the HTTP PUT verb, then you can simply do a regular POST instead.

Delete a user

Deleting a user can be done by sending an HTTP DELETE request to /api/users, specifying the ID of the user in question.

Try it out
DELETE /api/users/{id}

The system will look for the ID in the database and return 200 OK if the record was deleted successfully, or 404 Not found if it (no longer) exists.

If the software you are using is not able to send the HTTP DELETE verb, then you can also do a POST with the extra parameter _method=DELETE.

Troubleshooting tips

  • If you see an error Email is not a valid email address, then please refer to the Settings section on this page to confirm you have made the correct settings in your SuperSaaS account
  • If the button redirects the user but does not appear to actually log him in, then the cookie gets lost somewhere along the way. The most common cause is that the domain you are using to access the API is different from the domain of the schedule you are sending the user to; they should be the same.
  • If you allow people on your site without logging in, you probably want to ensure that they can not access the automatic login to SuperSaaS. Your code probably would not generate a valid login for anonymous users, but if it does then all anonymous users would be able to see and change each other’s appointments. If you want to be able for anonymous users to see the schedule before asking them to log in, you could provide a regular link for them to the schedule instead.
  • If you get the error Bad request – unknown attribute: field-1, then you used the variable name with a dash instead of an underscore in a POST call. So you should use user[field_1] in REST calls and <field-1> in XML calls.