Digicollect API v1 documentation

Introduction

Welcome to the Digicollect API documentation.

The Digicollect API allows you to read data from your Digicollect site and integrate it in your own software.

Authentication

All API requests must use a secure HTTP connection (HTTPS) to "api.digicollect.nl". For authentication you need to provide an API key as parameter (api_key) or header (this is the preferred way, the header name is X-Api-Key). If no API key or an invalid key is provided, the status code 401 will be returned. Please contact support-NL@iraiser.eu to get an API key for your Digicollect site.

For example, when you have an API key "12345", then the following will be a valid API request:

GET https://api.digicollect.nl/v1/donations?api_key=12345

Example for a valid API request using curl and authentication via header:

curl -H "X-Api-Key: 12345" https://api.digicollect.nl/v1/donations

Requests

The following HTTP request types are supported:

Responses

The API will return the following HTTP status codes for a request:

For a successful GET request, the response body will include one or more JSON objects with the requested data. The key will always be the resource that was requested, the singular form when one object was requested or the plural form when requesting a multiple objects.

A successful POST response body will include one JSON object with the newly created data.

A successful PATCH response body will include one JSON object with the newly updated resource.

For example, the response for requesting a single object or creating an object:

{
  "donation": {
    "id": 1,
    ...
  }
}

Example response for requesting multiple objects:

{
  "donations": [
    {
      "id": 1,
      ...
    },
    {
      "id": 2,
      ...
    }
  ]
}

Pagination

Requests that return many objects (List operations) will be limited to 25 objects by default. When more results are available, the response will include a links object with first/last/prev/next links.

Sample links object:

{
  "links": {
    "pages": {
      "last": "https://api.digicollect.nl/v1/donations?page=34",
      "next": "https://api.digicollect.nl/v1/donations?page=2"
    }
  }
}

You can use the following parameters to specify pages and to customize the page size:

Curl example for retrieving a maximum of 100 donations with page number 1:

curl -H "X-Api-Key: 12345" "https://api.digicollect.nl/v1/donations?per_page=100&page=1"

The response will also include the following keys to supply information about the number of available objects and the current pagination:

{
  "total_entries": 30,
  "total_pages": 3,
  "per_page": 10,
  "current_page": 1
}

New and updated objects

Each object includes the attributes created_at and updated_at which indicate when the record was created (created_at) and when the record was last changed (updated_at). These attributes can be used as filter to retrieve only new or updated objects.

For all requests that return many objects (List operations) you can the following parameters to return new or updated objects after a given datetime:

Both parameters are a datetime in ISO 8601 format.

Curl example for retrieving donations created on and after midnight (UTC) on 1 January 2016:

curl -H "X-Api-Key: 12345" "https://api.digicollect.nl/v1/donations?created_after=2015-12-31T23:59:59Z"