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.
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
The following HTTP request types are supported:
GET
- Request to one or more resources. The result will be returned as JSON.POST
- Create a new resource and return the result as JSON.PATCH
- Update attribute(s) of a resource and return the result as JSON.The API will return the following HTTP status codes for a request:
200 OK
- The GET
or PATCH
request was successful.201 Created
- The POST
request was successful.400 Bad Request
- The request contains an invalid parameter or payload.401 Unauthorized
- No valid API key was provided (see above how to authenticate).403 Forbidden
- Access to the requested resource was denied.404 Not Found
- A requested resource could not be found.422 Unprocessable
- Entity could not be processed because fields were missing or invalid.500 Server Error
- Something went wrong on the server side when trying to process the 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,
...
}
]
}
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:
page
(default: 1
) - page numberper_page
(default: 25
, max: 100
) - number of objects to return per pageCurl 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
}
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:
created_after
- return only objects that were created after the given datetime (ordered by created_at
)updated_after
- return only objects that were updated after the given datetime (ordered by updated_at
)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"