How does the API work?

With the API, you can perform all necessary actions to manage appointments and customers from your OnlineAfspraken.nl agenda within your own application. You do this by sending REST requests to our API server. A REST request is a unique URL with the required parameters for your request. In the API reference, you will find an overview of all API methods and their required parameters. Each REST request must be signed using a signing procedure, which is explained below. Every REST request returns an XML document containing the response from the API method.

Please note: Our API supports more case-specific features than those described in this public documentation, including an SSO solution. Please contact support to learn more about the available options.

Composing the parameters

A REST call has a number of required parameters, and a number of optional parameters which may differ for each API method. An API call always contains:

api_key - Your personal API key. You can find your API key in your OnlineAfspraken.nl backend, under "Settings" -> "Additional functionality" -> "API data".

api_salt - The current timestamp. The timestamp is also used to determine the validity of your request. A URL is valid for a maximum of 5 minutes. For this reason, it is important that the timestamp of your server is synchronized with our server. This is not always the case. In every response, the timestamp of our server is always included so that you can always determine the difference compared to your server, and adjust the salt accordingly. Our server is set to GMT +1, which is standard for a Dutch web server. At this moment, the timestamp on our server is 1751378115. Your salt must therefore always be smaller than this value, but no more than 300 smaller than this value.

api_signature - Your signature for this API call

method - The desired API method

Optionally, additional parameters are added per API method in the form of key/value.

Signing the API call

To sign the request, the desired API function and all variables are sorted in ascending alphabetical order by key and concatenated as key-value pairs without spaces. After that, the api_secret is appended, which—just like the api_key—is a fixed value. This value is known to both the application and the client but is never sent along in a transaction. Then, the salt is added to the string to be encrypted. The salt is the current timestamp.

Example

To sign the API call **getResource**, where we want to retrieve the resource with ID 8, the string to be signed looks like this:

id8methodgetResourceAPISECRETSALT

(where **APISECRET** and **SALT** are replaced by your *api\_secret* and the current timestamp) The **api\_signature** is then a sha256 hash of this string, like so:

  
  $api_signature = sha256('id8methodgetResourceAPISECRETSALT');  

Existing implementations may also use **sha1** to generate the signature.

Executing an API call via the REST protocol

After the parameters for this API call have been signed with the code above, you can construct the REST call. The REST call for the example mentioned is as follows:

  
  https://agenda.onlineafspraken.nl/APIREST?method=getResource&id=8&api_key=xx&api_signature=xx&api_salt=xx  

Here, **api\_key** is your own API key, **api\_signature** is the signature obtained through the sha256 hashing method, and **api\_salt** is the same timestamp that was used to generate the signature. You never send your **api\_secret**!

Processing response XML

After you have executed the REST call to our server via an HTTP request, you will receive an XML message. This message always consists of 2 parts:

Status

In the status, you will find Status=Success in the case of a successful API call, and Status=Failed, along with an error message and error code, in the case of a failed API call. In addition, the status segment always contains the date and time of the message. For calls that retrieve multiple objects (getAppointments, getCustomers, etc.), the status section also includes information about the number of records.

Example of a successful API call

<Response>  
  <Status>  
    <Status>success</Status>  
    <Date>2025-07-14 12:34:56</Date>  
    <Stats>  
      <Limit>100</Limit>  
      <Offset>0</Offset>  
      <Records>100</Records>  
      <TotalRecords>257</TotalRecords>  
    </Stats>  
  </Status>  
  ...  
</Response>  

Example of a failed API call

<Response>  
  <Status>  
    <Status>failed</Status>  
    <Message>API required parameter id not found.</Message>  
    <Code>B57</Code>  
    <Date>2025-07-14 12:34:56</Date>  
  </Status>  
  ...  
</Response>  

Objects

In the objects segment, you will find one or more objects in the case of a successful API call. The object differs per API method; see the API reference for the expected objects and the elements that are returned.

Example of an agenda object

<Response>  
  ...  
  <Objects>  
    <Agenda>  
      <Id>1</Id>  
      <Name>Some calendar</Name>  
      <DateFormat>yyyy-mm-dd</DateFormat>  
      <TimeFormat>hh:mm:ss</TimeFormat>  
      <AlignGrid>15</AlignGrid>  
      <IsDefault>1</IsDefault>  
    </Agenda>  
  </Objects>  
</Response>  