Digicollect API v1 documentation

Collection boxes

Represents a collection box on a Digicollect site.

List all Collection boxes

Get a list of collection boxes for the current site or group.

GET /v1/collection-boxes
GET /v1/groups/:group_id/collection-boxes

The result will be returned as JSON with a collection_boxes key. This will be an array with objects containing Collection box attributes.

Curl example:

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

Example response body:

{
  "collection_boxes": [
    {
      "id": 1,
      "slug": "john-doe",
      "created_at": "2017-06-26T14:50:14Z",
      "updated_at": "2017-07-12T16:27:43Z",
      "owner": {
        "id": 2,
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@digicollect.nl",
        "locale": "nl"
      },
      "description": "Dolorum animi qui nihil iure dolore velit. Rerum eius et quo.",
      "total_amount": "125.0",
      "total_donations": 2,
      "visible": true,
      "url": "https://demo1.digicollect.nl/john-doe",
      "pool": {
        "id": 3,
        "name": "Pool test",
        "position": 1
      },
    }
  ],
  "links": {
    "pages": {
      "last": "https://api.digicollect.nl/v1/collection-boxes?page=34&per_page=1",
      "next": "https://api.digicollect.nl/v1/collection-boxes?page=2&per_page=1"
    }
  },
  "total_entries": 34,
  "total_pages": 34,
  "per_page": 1,
  "current_page": 1
}

Retrieve a single Collection box

Retrieve a single collection box for the current site. A collection box can be queried by ID or slug.

GET /v1/collection-boxes/1
GET /v1/collection-boxes/john-doe

The result will be returned as JSON with a collection_box key. This will be an object containing Collection box attributes.

Curl example:

curl -H "X-Api-Key: 12345" https://api.digicollect.nl/v1/collection-boxes/1
curl -H "X-Api-Key: 12345" https://api.digicollect.nl/v1/collection-boxes/john-doe

Example response body:

{
  "collection_box": {
    "id": 1,
    "slug": "john-doe",
    "created_at": "2022-09-26T14:50:14Z",
    "updated_at": "2022-09-26T14:50:14Z",
    "owner": {
      "id": 2,
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@digicollect.nl",
      "locale": "nl"
    },
    "description": "Dolorum animi qui nihil iure dolore velit. Rerum eius et quo.",
    "total_amount": "125.0",
    "total_donations": 2,
    "visible": true,
    "url": "https://demo1.digicollect.nl/john-doe",
    "pool": {
      "id": 3,
      "name": "Pool test",
      "position": 1
    },
    "consents": [
      {
        "consent_type": "terms_conditions",
        "consent_status": "granted",
        "granted_at": "2022-09-26T14:50:14Z",
        "consent_text": "Op onze dienstverlening zijn onze <a href='/algemene-voorwaarden' target='_blank'>Algemene Voorwaarden</a> &amp; <a href='/privacy' target='_blank'>Privacyverklaring</a> van toepassing.",
        "url": "https://demo1.digicollect.nl/aanmwelden/email",
        "terms_conditions_version": "V5 22-06-2016 13:09",
        "privacy_version": "V2 07-12-2018 08:34"
      }
    ]
  }
}

Create a new Collection box

Create a new collection box on the current site or group.

POST /v1/collection-boxes
POST /v1/groups/:group_id/collection-boxes

The request should contain the following attributes in a JSON object:

Name Type Description Required
owner object The owner of the collection box. See below. Yes
description string Description (motivation) for the collection box. Not required when a default motivation has been configured. No
visible boolean Indicates if the collection box is visible. Default is true. No
external_customer string Reference to an external customer ID. No
external_agent string Reference to an external agent ID. No
send_welcome_email boolean When set to true, the welcome email will be sent when the collection box was successfully created. Please note that the collection box must be visible in order to trigger the email. Default is false. No

The owner object should contain the following attributes:

Name Type Description Required
first_name string The first name of the owner. Yes
infix string The infix of the owner. No
last_name string The last name of the owner. Yes
email string The email address of the owner. unique Yes

Example request body:

{
  "owner": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@digicollect.nl"
  },
  "description": "Dolorum animi qui nihil iure dolore velit. Rerum eius et quo."
}

Curl example:

curl -H "X-Api-Key: 12345" -H "Content-Type: application/json" -d '{ "owner": { "first_name": "John", "last_name": "Doe", "email": "john.doe@digicollect.nl" }, "description": "Lorem ipsum" }' https://api.digicollect.nl/v1/collection-boxes

The result will be returned as JSON with a collection_box key. This will be an object containing Collection box attributes.

Example response body:

{
  "collection_box": {
    "id": 1,
    "slug": "john-doe",
    "created_at": "2017-06-26T14:50:14Z",
    "updated_at": "2017-07-12T16:27:43Z",
    "owner": {
      "id": 2,
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@digicollect.nl"
    },
    "description": "Dolorum animi qui nihil iure dolore velit. Rerum eius et quo.",
    "total_amount": "125.0",
    "total_donations": 2,
    "visible": true,
    "url": "https://demo1.digicollect.nl/john-doe"
  }
}

Update a single collection box

Update a single collection box for the current site.

PATCH /v1/collection-boxes/1
PATCH /v1/collection-boxes/john-doe

The request is allowed to contain one or more of the following attributes in a JSON object:

Name Type Description Required
description string Description (motivation) for the collection box. Not required when a default motivation has been configured. No
visible boolean Indicates if the collection box is visible. Default is true. No
external_customer string Reference to an external customer ID. No
external_agent string Reference to an external agent ID. No

Example request body:

{
  "description": "Dolorum animi qui nihil iure dolore velit. Rerum eius et quo.",
  "visible": false
}

Curl example:

curl -X PATCH -H "X-Api-Key: 12345" -H "Content-Type: application/json" -d '{ "description": "Lorem ipsum", "visible": "false" }' https://api.digicollect.nl/v1/collection-boxes/999

Example response body:

{
  "collection_box": {
    "id": 1,
    "slug": "john-doe",
    "created_at": "2017-06-26T14:50:14Z",
    "updated_at": "2017-07-12T16:27:43Z",
    "owner": {
      "id": 2,
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@digicollect.nl"
    },
    "description": "Dolorum animi qui nihil iure dolore velit. Rerum eius et quo.",
    "total_amount": "125.0",
    "total_donations": 2,
    "visible": false,
    "url": "https://demo1.digicollect.nl/john-doe"
  }
}

Collection box attributes

A collection_box response object contains the following attributes:

Name Type Description
id number Unique identifier for this collection box.
slug string Unique identifier for this collection box, used to create a "nice" collection box URL.
group_id number Unique identifier for the group associated with the collection box. optional
created_at string The time (ISO 8601 format) when the collection box was created.
updated_at string The time (ISO 8601 format) when the collection box was last updated.
description string Description for the collection box.
owner object Represents the owner for the collection box. (see below)
total_amount string The amount that was donated to the collection box (with decimals).
total_donations number The number of donations for the collection box.
visible boolean Indicates whether the collection box is visible or not.
url string The URL to the collection box.
external_customer string Reference to an external customer ID when the collection box was created. optional
external_agent string Reference to an external agent ID when the collection box was created. optional
pool object Represents the active pool for the collection box. See Collection box - Pool object. optional
consents array List of consents associated with the collection box. See Collection box - Consent object. optional

The owner object for a collection_box contains the following attributes:

Name Type Description
id number Unique identifier for the collection box owner.
first_name string The first name of the owner.
infix string The infix of the owner. optional
last_name string The last name of the owner.
email string The email address of the owner.
avatar_url string The URL to the avatar image of the owner. optional
phone_number string Phone number of the owner. optional
locale string The locale of the owner (nl, en, de, etc).

Collection box - Pool object

The pool object for a collection_box contains the following attributes:

Name Type Description
id number Unique identifier for the collection box active pool.
name string The name of the active pool.
position number The position of the active pool.

This object contains information about a specific consent an user has given, for example the processing of personal data when signing up.

Some consents can also be revoked later on by the user, after which the status will change to revoked and the attribute revoked_at will be returned.

Attribute Type Description
consent_type string Type of consent. See below for possible values with their description.
consent_status string Status of the consent (granted or revoked).
granted_at string The time (ISO 8601 format) when the consent was granted.
revoked_at string The time (ISO 8601 format) when the consent was revoked. optional
consent_text string The consent text the user has agreed to.
url string The URL of the webpage where the consent was given.
terms_conditions_version string Version of terms and conditions when the consent was given.
privacy_version string Version of privacy statement when the consent was given. optional

Available consent types (given by users) are:

Consent type Description
terms_conditions Accepting the terms and conditions.
contact_phone Allowing use of the phone number for tips.
contact_phone_commercial Allowing use of the phone number for marketing purposes.