Collectmaxx API
- Remco Raaijmakers
- Daniel Schurr (Unlicensed)
- Jasper van eck (Unlicensed)
- 1 Introduction
- 1.1 GraphQL
- 1.2 API endpoint
- 1.2.1 Test endpoint
- 1.3 API Keys
- 1.4 Code example
- 2 APIs
- 2.1 Import
- 2.1.1 Required fields
- 2.1.2 Status codes
- 2.1.3 Input options
- 2.1.4 Examples
- 2.1.4.1 Row Input
- 2.1.4.2 File Input
- 2.1.4.3 Search batches
- 2.2 PayLink
- 2.2.1 Status codes
- 2.2.2 Examples
- 2.2.2.1 Create PayLink
- 2.2.2.2 Simple PayLink search
- 2.2.2.3 Find Single PayLink
- 2.2.2.4 Search PayLink with record identifer
- 2.2.2.5 Advanced PayLink search
- 2.3 E-Mandate
- 2.3.1 Status codes
- 2.3.2 Examples
- 2.3.2.1 Create Mandate
- 2.3.2.2 Simple Mandate search
- 2.3.2.3 Find Single Mandate
- 2.3.2.4 Advanced Mandate search
- 2.4 Voice
- 2.4.1 Examples
- 2.4.1.1 Stop Calling
- 2.4.1 Examples
- 2.1 Import
- 3 Webhook events
- 3.1 Voice
- 3.1.1 Call completed
- 3.1.2 Example
- 3.2 PayLink
- 3.2.1 Event
- 3.2.2 Example Paid
- 3.3 Voice webhook V1
- 3.1 Voice
Introduction
With our API it is possible to create PayLinks, e-Mandates and import records for our scripts. To use the PayLink and e-Mandate service, additional configuration and setup are required. Please contact our customer support if you would like to use additional services.
Please also read our Import and Result Data formats document.
GraphQL
Our API is written in GraphQL. On How To GraphQL you can read the fundamentals. Creating PayLinks should be as easy as using a REST API. We have added some examples of how to use our API with a GraphQL Client.
To explore our API and its documentation you could use the Altair GraphQL Client. This client has the option to set the required authentication header. Watch this demo video to view how to use the built-in documentation browser.
Example collection for Altair
To explore our API and view all available fields, import the following collection to the Altair Client and update the header with your API key.
API endpoint
https://reminders.alphacommapi.com/v1We use load balancers so a IP change is possible at any time.
Test endpoint
Contact us for the test endpoint and credentials.
API Keys
You will need an access key to connect to our API. Your keys can be managed through our portal. At the portal go to "Account → API keys". You must be a portal manager for your company to access this page.
Key usage
For each request set the "X-AUTH-TOKEN" HTTP header with your key.
Key IP restriction
It is possible to allow keys to only work from certain IP addresses.
127.1.1.1
192.1.0.0/32Code example
We created one request example in PHP to get you started.
APIs
Through our API we provide multiple services. The requirements for fields are defined in the API itself. Use a GraphQL client to view the documentation. In this document, we will give you some examples to get started.
All the dates fields in our responses are formatted in RFC 3339, 'Y-m-d\TH:i:sP'.
Import
The import API is an alternative for our batch SFTP (CSV) import. Through this endpoint, you are able to import records. The records are batched and visible in the portal on the import page.
When sending records to our API, we still starting import the records according to your account’s Import schedule. These import windows are visible at your upload page.
Required fields
The scripts that are set up in our portal may be set up for voice messages, text messages or emails, that optionally contain a PayLink or e-Mandate. Each script has its own set of required fields.
When a new script is set up we will provide a list of required fields. You can also use our matrix of required fields for medium and services.
Status codes
More information about status codes, which are used at the portal and API.
Batch statuses
Name | Description |
|---|---|
empty | No records added to this batch yet. |
queued | Records are waiting to be processed. |
running | Records are being processed. |
done | Records have finished processing. |
error | Something went wrong. |
Record statuses
Name | Description |
|---|---|
notLoaded | Records that could not be read. |
loaded | Records that have been read. |
rejected | Records that could not be converted into a job. |
accepted | Records that could be converted into a job. |
enriching | Records that are currently enriching. |
created | Records that have created a new job. |
updated | Records that have updated an existing job. |
dropped | Records that could not be saved to the database. |
Input options
Through the 'addRecords' mutation you are able to add records.
Argument | Description | When to use |
|---|---|---|
rows [RowInput!] | An endpoint that has a preset of fields. | This is the preferred way to deliver your records and usable in most cases. |
file [FileInput!] | Base64 encoded file. For example: csv, xml, xlsx, xls, ods. | For large batch import, 1000 or more. |
If you have questions please contact us.
Examples
When we set up a new script we will inform you about the required fields.
Row Input
This is an example of a mail with PayLink record using the RowInput.
POST Query body
mutation addRecords (
$file: FileInput,
$rows: [RowInput!]
) {
import {
addRecords(file: $file, rows: $rows) {
name
action
status
records {
scriptId
status
reference
messages {
context
message
level
}
}
}
}
}Variables
Response 200
File Input
This is an example with FileInput. Your file should be sent as a Base64 encoded string. An imported file will always respond with a status queued. The slight delay is deliberate because we need time to process all records. It is possible to send a second request to get the status of the batch.
POST Query body
Variables
Response 200
Search batches
This is an example of searching for a batch by name.
POST Query body
Variables
Response 200
PayLink
To use this service we need to configure your iDEAL bank credentials and set up a landing page. Please contact us if you would like to use this service.
Status codes
Name | Description |
|---|---|
ready | PayLink is created in our service. |
started | Transaction has been started. |
partially_paid | A part of the original PayLink amount is paid. |
paid | The complete PayLink amount is paid. |
cancelled | The last transaction of the PayLink has been cancelled. |
failed | The last transaction of the PayLink has failed. |
Examples
To make your start easier we have added some examples of common actions.
Keep in mind to use the POST method on all your request.
Create PayLink
When using GraphQL you have the ability to define what fields you get in the response. For this example, we only want the id of the created PayLink and the URLs.
POST Query body
Variables
This is the minimal information we need to create a PayLink.
Us the field visibleUntil to set the date when payment should not be possible anymore.
Response 200
Simple PayLink search
A basic search on all PayLinks.
POST Query body
Variables
No variables are needed for this query.
Response 200
Find Single PayLink
An example of how to get the status of a single PayLink.
POST Query body
Variables
Response 200
Search PayLink with record identifer
PayLinks can not only be created through our API but also though the import to our scripts. In this last case the PayLink is delivered by us via email or SMS.
During a record import you are required to define the ‘idenfification_identifier' or also called 'reference’. In case you want to know what the current status of the PayLink is your are able to search our PayLink service with this reference.
POST Query body
Variables
Response 200
Advanced PayLink search
An example of how to find all PayLinks with the status paid created on 08-02-2019.
You have the option to set filters, order, offset and limit. All the options are defined in the API docs.
POST Query body
Variables
Response 200
E-Mandate
To use this service we need to configure your e-Mandate bank credentials and setup a landing page. Please contact us if you would like to use this service.
Status codes
Name | Description |
|---|---|
new | Mandate is created on our service. |
pending | Waiting for second authorization. |
success | Mandate is given. |
Examples
To make your start easier we have added some examples of common actions.
Keep in mind to use the POST method on all your request.
Create Mandate
When using GraphQL you have the ability to define what fields you get in the response. For this example, we only want the id, reference, URLs and type.
POST Query body
Variables
Example values.
Response 200
Simple Mandate search
A basic search query for all Mandates.
POST Query body
Variables
No variables are needed for this query.
Response 200
Find Single Mandate
An example of how to get the status of a single Mandate.
POST Query body
Variables
Response 200
Advanced Mandate search
An example of how to find all e-Mandates with the status success, created on 08-02-2019.
You have the option to set filters, order, offset and limit. All the options are defined in the API docs.
POST Query body
Variables
Response 200
Voice
To use this service we need to configure a voice script. Please contact us if you would like to use this service.
Examples
To make your start easier we have added some examples of common actions.
Stop Calling
Use this action to remove any leftover scheduled voice calls, related to the specified scriptId and reference.
POST Query body
Variables
Response 200
Webhook events
Voice
Call completed
Field |
| Format |
|---|---|---|
datetime | When the event occurred | RFC3339 |
id | Identifying the call. | UUID
|
serviceId | Identifier of the Call Request. | UUID
|
serviceId | voice |
|
reference | Identifier used during import, also know as identification_identifier |
|
event |
| |
data |
| See Data table below. |
Data |
|
|
|---|---|---|
direction | Call direction | ENUM DIRECTION |
status | The call status | ENUM STATUS |
localNumber |
| E164 |
remoteNumber |
| E164 |
events | Array of events during the call, Empty when call is not answered. |
|
answeredOn | not set if the call has not been answered. | RFC3339 |
Example
PayLink
Event
Field |
| Format |
|---|---|---|
datetime | When the event occurred | RFC3339 |
id | Identifying the event uniquely | UUID
|
serviceId | Identifier of the PayLink | UUID
|
serviceId | paylink |
|
reference | Identifier used during import, also know as identification_identifier | Empty when created through our API. |
event |
| |
data |
|
Example Paid
Voice webhook V1
Call completed Legacy format
The voice service supports the use of webhook messages. When a voice call has been completed the result will be reported to your webhook URL. We can authenticate to your webhook with basic access authentication.
Contact us to configure your webhook URL.
Format
The webhook request is a standard HTTP POST request with a JSON body, which is formatted as follows.
Field |
| Format |
|---|---|---|
id | UUID, identifying the call uniquely |
|
attributes | Contains the 'reference' used at import (identification_identifier). |
|
direction | Call direction | ENUM DIRECTION |
status | The call status | ENUM STATUS |
localNumber |
| E164 |
remoteNumber |
| E164 |
events | Array of events during the call, Empty when call is not answered. |
|
createdOn |
| RFC3339 |
updatedOn |
| RFC3339 |
answeredOn | not set if the call has not been answered. | RFC3339 |
How to determine a call has reached the success point
To determine a call was successful a defined point in the voice message should be reached.
This is always an AddResult type node with a data result value success-ok
Example message for an outbound call
Example message for an anonymous or not recognized an inbound call
It is possible some is calling from a phone number we cannot match to a record or they have blocked their phone number.
In this case, we cannot provide the attribute reference.