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 REST an 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/v1
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 will need to 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/32
Code 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 by day of import and visible in the portal at the import page.
The reminder results are reported at the end of the day in one or multiple result files, grouped by script. For more information see our Import and Result Data formats document.
Required fields
The scripts that are setup in our portal may be setup 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 setup we will provide a list of required fields.
Status codes
More information about status codes, these 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 setup a new script we will inform you about the required fields.
Row Input
This an example of a mail with PayLink record using the RowInput.
Query
mutation addRecords (
$file: FileInput,
$rows: [RowInput!]
) {
import {
addRecords(file: $file, rows: $rows) {
name
action
status
records {
scriptId
status
messages {
context
message
level
}
}
}
}
}
Variables
{
"rows": [
{
"reference": "f0e7a0c3",
"script": "1001",
"personFamilyName": "Alphacomm",
"toMailAddress": "reminders@alphacomm.nl",
"invoiceDescription": "Example payment",
"invoiceDate": "2019-04-04",
"invoiceDueDate": "2019-07-30",
"invoiceReference": "40824524",
"invoiceCurrency": "EUR",
"invoiceAmount": "56445",
"invoiceNumber": "249075245",
"personBirthDay": "2000-01-01"
}
]
}
Response
{
"data": {
"import": {
"addRecords": {
"name": "20190403-965",
"action": "IMPORT",
"status": "done",
"records": [
{
"scriptId": "1001",
"status": "accepted",
"messages": []
}
]
}
}
}
}
File Input
This is an example with FileInput. Your file should be send as 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's possible to send a second request to get the status of the batch.
Query
mutation addFile (
$file: FileInput,
$rows: [RowInput!]
) {
import {
addRecords(file: $file, rows: $rows) {
name
action
status
}
}
}
Variables
{
"file": {
"extension": "csv",
"contents": "<<BASE64 ENCODED STRING>>"
}
}
Response
{
"data": {
"import": {
"addRecords": {
"name": "20190404-579",
"action": "IMPORT",
"status": "queued",
"records": []
}
}
}
}
Search batches
This is an example of searching for a batch by name.
Query
query ImportSearch(
$filters: BatchFiltersInput
) {
import {
batches(
filters: $filters
) {
items {
name
action
status
}
pagination {
offset
limit
total
}
}
}
}
Variables
{
"filters": {
"name": {
"equalTo": "Test"
}
}
}
Response
{
"data": {
"import": {
"batches": {
"items": [
{
"name": "Test",
"action": "VALIDATE",
"status": "empty"
}
],
"pagination": {
"offset": 0,
"limit": 20,
"total": 1
}
}
}
}
}
PayLink
To use this service we need to configure your iDEAL bank credentials and setup 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
Query
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.
mutation createPayLink($payLink: PayLinkInput!){
payLink {
create (payLink: $payLink) {
id
shortUrl
longUrl
}
}
}
Variables
This is the minimal information we need to create a PayLink.
By default, there is no expiration date to pay a PayLink. Us the field visibleUntil to set the date when payment should not be possible anymore.
{
"payLink": {
"personName": "Alphacomm",
"invoiceAmount": "15497",
"invoiceCurrency": "EUR",
"invoiceDescription": "Example",
"invoiceReference": "103482",
"invoiceDate": "2019-02-12T10:00:00+00:00"
}
}
Response
{
"data": {
"payLink": {
"create": {
"id": "a62c3726-d3b2-4b8c-8e4c-48ee0fd9451c",
"shortUrl": "https://ibanaccept.com/u8t1nbw",
"longUrl": "https://alphacomm.ibanaccept.com/pay/a62c3726-d3b2-4b8c-8e4c-48ee0fd9451c"
}
}
}
}
Simple PayLink search
A basic search on all PayLinks.
Query
query {
payLink {
payLinks {
items {
status
id
}
}
}
}
Variables
No variables needed for this query.
{}
Response
{
"data": {
"payLink": {
"payLinks": {
"items": [
{
"status": "paid",
"id": "a6e8b63c-927f-476b-8d47-d323e20e1a4f"
},
{
"status": "cancelled",
"id": "348bd90d-da76-4211-93c3-601cbb15f33a"
},
{
"status": "ready",
"id": "389f0187-6b5d-4896-8d78-e56a6bb1a156"
}
]
}
}
}
}
Find Single PayLink
An example of how to get the status of a single PayLink.
Query
query PayLinks(
$filters: PayLinkFiltersInput
) {
payLink {
payLinks (
filters: $filters
) {
items {
id
personName
personGender
status
amountPaid
createdOn
updatedOn
}
}
}
}
Variables
{
"filters": {
"id": {
"equalTo": "5be41c4f-9fe6-403d-980b-5edc0139ee70"
}
}
}
Response
{
"data": {
"payLink": {
"payLinks": {
"items": [
{
"id": "5be41c4f-9fe6-403d-980b-5edc0139ee70",
"personName": "Demo",
"personGender": "U",
"status": "paid",
"amountPaid": 0,
"createdOn": "2019-02-05T09:57:14+00:00",
"updatedOn": "2019-02-05T09:57:14+00:00"
}
]
}
}
}
}
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.
Query
query PayLinks(
$filters: PayLinkFiltersInput
$order: PayLinkOrderInput
$offset: Int
$limit: Int
) {
payLink {
payLinks (
filters: $filters
order: $order
offset: $offset
limit: $limit
) {
items {
id
personName
personGender
status
amountPaid
createdOn
updatedOn
}
pagination {
offset
limit
total
}
}
}
}
Variables
{
"filters": {
"status": {
"equalTo": "paid"
},
"createdOn": {
"greaterThan": "2019-02-08T00:00:00+00:00",
"lesserThan": "2019-02-09T00:00:00+00:00"
}
},
"order": {
"createdOn": "DESCENDING"
},
"offset": 0,
"limit": 20
}
Response
{
"data": {
"payLink": {
"payLinks": {
"items": [
{
"id": "5be41c4f-9fe6-403d-980b-5edc0139ee70",
"personName": "Demo",
"personGender": "U",
"status": "paid",
"amountPaid": 0,
"createdOn": "2019-02-05T09:57:14+00:00",
"updatedOn": "2019-02-05T09:57:14+00:00"
},
{
"id": "96f3cf79-98ab-43d1-80ca-fa5c9fccab23",
"personName": "Test Person",
"personGender": "U",
"status": "paid",
"amountPaid": 0,
"createdOn": "2019-02-01T14:49:35+00:00",
"updatedOn": "2019-02-01T14:49:36+00:00"
}
],
"pagination": {
"offset": 0,
"limit": 0,
"total": 2
}
}
}
}
}
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
Query
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, the URLs and type.
mutation createMandate($mandate: MandateInput!){
mandate {
create (mandate: $mandate) {
id
reference
shortUrl
longUrl
type
}
}
}
Variables
Example values.
{
"mandate": {
"personName": "Alphacomm",
"reference": "AC-HUUR"
"type": "RCUR",
"reason": "huur",
"debtorReference": "20190301"
}
}
Response
{
"data": {
"mandate": {
"create": {
"id": "4442ddf6-7371-4e6a-8939-087f8fd3b17c",
"reference": "AC-HUUR",
"shortUrl": "https://betaalmachtiging.nl/akps797",
"longUrl": "https://alphacomm.betaalmachtiging.nl/pay/94e592f0-9f21-4404-bdfe-a6e51c6bf547",
"type": "RCUR"
}
}
}
}
Simple Mandate search
A basic search query for all Mandates.
Query
query {
mandate {
mandates {
items {
status
id
}
}
}
}
Variables
No variables needed for this query.
{}
Response
{
"data": {
"mandate": {
"mandates": {
"items": [
{
"status": "new",
"id": "a6e8b63c-927f-476b-8d47-d323e20e1a4f"
},
{
"status": "pending",
"id": "348bd90d-da76-4211-93c3-601cbb15f33a"
},
{
"status": "success",
"id": "389f0187-6b5d-4896-8d78-e56a6bb1a156"
}
]
}
}
}
}
Find Single Mandate
An example of how to get the status of a single Mandate.
Query
query Mandates(
$filters: MandateFiltersInput
) {
mandate {
mandates (
filters: $filters
) {
items {
id
personName
status
createdOn
updatedOn
}
}
}
}
Variables
{
"filters": {
"id": {
"equalTo": "5be41c4f-9fe6-403d-980b-5edc0139ee70"
}
}
}
Response
{
"data": {
"mandate": {
"mandates": {
"items": [
{
"id": "5be41c4f-9fe6-403d-980b-5edc0139ee70",
"personName": "Demo",
"status": "success",
"createdOn": "2019-02-05T09:57:14+00:00",
"updatedOn": "2019-02-05T09:57:14+00:00"
}
]
}
}
}
}
Advanced Mandate search
An example on 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.
Query
query Mandates(
$filters: MandateFiltersInput
$order: MandateOrderInput
$offset: Int
$limit: Int
) {
mandate {
mandates (
filters: $filters
order: $order
offset: $offset
limit: $limit
) {
items {
id
personName
status
createdOn
updatedOn
}
pagination {
offset
limit
total
}
}
}
}
Variables
{
"filters": {
"status": {
"equalTo": "success"
},
"createdOn": {
"greaterThan": "2019-02-08T00:00:00+00:00",
"lesserThan": "2019-02-09T00:00:00+00:00"
}
},
"order": {
"createdOn": "DESCENDING"
},
"offset": 0,
"limit": 20
}
Response
{
"data": {
"mandate": {
"mandates": {
"items": [
{
"id": "5be41c4f-9fe6-403d-980b-5edc0139ee70",
"personName": "Demo",
"status": "success",
"createdOn": "2019-02-05T09:57:14+00:00",
"updatedOn": "2019-02-05T09:57:14+00:00"
},
{
"id": "96f3cf79-98ab-43d1-80ca-fa5c9fccab23",
"personName": "Test Person",
"status": "success",
"createdOn": "2019-02-01T14:49:35+00:00",
"updatedOn": "2019-02-01T14:49:36+00:00"
}
],
"pagination": {
"offset": 0,
"limit": 0,
"total": 2
}
}
}
}
}
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.
Keep in mind to use the POST method on all your request.
Stop Calling
Use this action to remove any leftover scheduled voice calls, related to the specified scriptId and reference.
Query
mutation stopCalling(
$scriptId: Int!
$reference: String!
){
voice {
stopCalling (
scriptId: $scriptId
reference: $reference
)
}
}
Variables
{
"scriptId": 18301,
"reference": "your_identifier"
}
Response
{
"data": {
"voice": {
"stopCalling": "done"
}
}
}
Webhook
The voice service supports the use of webHooks. When a voice call has been completed the result will be reported to your webhook URL. Contact us to configure your webhook URL.
The body looks as follows:
Field | Format | |
|---|---|---|
id | UUID, identifying the call uniquely | |
attributes | Contains the 'reference' used at import (identification_identifier). | |
direction | Call direction | ENUM DIRECTION outbound inbound |
status | The call status | ENUM STATUS ringing active finished no answer busy rejected invalid number failed |
localNumber | E164 | |
remoteNumber | E164 | |
events | Array of events during the call, nodeId: string, node identifier nodeType: string, ENUM NODETYPE order: int, event order type: string, ENUM EVENTTYPE data: array, data that is specific to the node type and event type time: string, RFC3339 Empty when call is not answered. | NODETYPE: AddResult CheckCallAttempt CheckCounter CheckGenderBirthday CheckVariable DTMF DTMFString Forward Hangup IsCallOutbound IsRemoteMobile IsRemoteVoiceMail IsTimeInInterval Sound WaitForSilence EVENTTYPE: NodeStart NodeUpdate NodeResult |
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
{
"nodeId": "success",
"nodeType": "AddResult",
"order": 16,
"type": "NodeResult",
"data": {
"result": "success-ok"
},
"time": "2020-05-06T08:43:11+00:00"
}
Use the NodeResult type with the data['result'] value when evaluating the events. The NodeId’s are more likely to change when altering voice script flows.
Example message for an outbound call
{
"id": "e7813601-21ae-465c-bd97-96367bebd0ca",
"attributes": {
"origin": "annabel",
"customer": "6500",
"script": "6512",
"job": "eb44f88bd968749a620765a382ef3c75c20a657c37499392d59958c5dd944652-06512",
"reference": "API reference / identification_identifier"
},
"direction": "outbound",
"status": "finished",
"localNumber": "31513703800",
"remoteNumber": "31640754459",
"events": [{
"nodeId": "vm_beep",
"nodeType": "Sound",
"order": 1,
"type": "NodeStart",
"data": [],
"time": "2020-05-06T08:42:55+00:00"
}, {
"nodeId": "vm_beep",
"nodeType": "Sound",
"order": 2,
"type": "NodeResult",
"data": [],
"time": "2020-05-06T08:42:59+00:00"
}, {
"nodeId": "vm_wait_for_silence",
"nodeType": "WaitForSilence",
"order": 3,
"type": "NodeStart",
"data": [],
"time": "2020-05-06T08:42:59+00:00"
}, {
"nodeId": "vm_is_vm",
"nodeType": "IsRemoteVoiceMail",
"order": 5,
"type": "NodeStart",
"data": [],
"time": "2020-05-06T08:43:00+00:00"
}, {
"nodeId": "text10",
"nodeType": "Sound",
"order": 7,
"type": "NodeStart",
"data": [],
"time": "2020-05-06T08:43:00+00:00"
}, {
"nodeId": "text10",
"nodeType": "Sound",
"order": 8,
"type": "NodeResult",
"data": [],
"time": "2020-05-06T08:43:05+00:00"
}, {
"nodeId": "filter",
"nodeType": "CheckGenderBirthday",
"order": 9,
"type": "NodeStart",
"data": [],
"time": "2020-05-06T08:43:05+00:00"
}, {
"nodeId": "filter",
"nodeType": "CheckGenderBirthday",
"order": 10,
"type": "NodeResult",
"data": {
"gender": "M",
"age": 2020,
"outcome": "man"
},
"time": "2020-05-06T08:43:05+00:00"
}, {
"nodeId": "text11m",
"nodeType": "Sound",
"order": 11,
"type": "NodeStart",
"data": [],
"time": "2020-05-06T08:43:05+00:00"
}, {
"nodeId": "text11m",
"nodeType": "Sound",
"order": 12,
"type": "NodeResult",
"data": [],
"time": "2020-05-06T08:43:08+00:00"
}, {
"nodeId": "name",
"nodeType": "Sound",
"order": 13,
"type": "NodeStart",
"data": [],
"time": "2020-05-06T08:43:09+00:00"
}, {
"nodeId": "name",
"nodeType": "Sound",
"order": 14,
"type": "NodeResult",
"data": [],
"time": "2020-05-06T08:43:10+00:00"
}, {
"nodeId": "success",
"nodeType": "AddResult",
"order": 15,
"type": "NodeStart",
"data": [],
"time": "2020-05-06T08:43:11+00:00"
}, {
"nodeId": "success",
"nodeType": "AddResult",
"order": 16,
"type": "NodeResult",
"data": {
"result": "success-ok"
},
"time": "2020-05-06T08:43:11+00:00"
}, {
"nodeId": "collect_id",
"nodeType": "Sound",
"order": 17,
"type": "NodeStart",
"data": [],
"time": "2020-05-06T08:43:11+00:00"
}, {
"nodeId": "collect_id",
"nodeType": "Sound",
"order": 18,
"type": "NodeResult",
"data": [],
"time": "2020-05-06T08:43:16+00:00"
}, {
"nodeId": "text22",
"nodeType": "Sound",
"order": 19,
"type": "NodeStart",
"data": [],
"time": "2020-05-06T08:43:17+00:00"
}, {
"nodeId": "text22",
"nodeType": "Sound",
"order": 20,
"type": "NodeResult",
"data": [],
"time": "2020-05-06T08:43:23+00:00"
}, {
"nodeId": "amount",
"nodeType": "Sound",
"order": 21,
"type": "NodeStart",
"data": [],
"time": "2020-05-06T08:43:24+00:00"
}, {
"nodeId": "amount",
"nodeType": "Sound",
"order": 22,
"type": "NodeResult",
"data": [],
"time": "2020-05-06T08:43:28+00:00"
}, {
"nodeId": "text30",
"nodeType": "Sound",
"order": 23,
"type": "NodeStart",
"data": [],
"time": "2020-05-06T08:43:29+00:00"
}, {
"nodeId": "text30",
"nodeType": "Sound",
"order": 24,
"type": "NodeResult",
"data": [],
"time": "2020-05-06T08:43:45+00:00"
}, {
"nodeId": "text31",
"nodeType": "Sound",
"order": 25,
"type": "NodeStart",
"data": [],
"time": "2020-05-06T08:43:46+00:00"
}, {
"nodeId": "text31",
"nodeType": "Sound",
"order": 26,
"type": "NodeResult",
"data": [],
"time": "2020-05-06T08:44:07+00:00"
}, {
"nodeId": "businesshours",
"nodeType": "IsTimeInInterval",
"order": 27,
"type": "NodeStart",
"data": [],
"time": "2020-05-06T08:44:07+00:00"
}, {
"nodeId": "businesshours_forward_switch",
"nodeType": "CheckVariable",
"order": 29,
"type": "NodeStart",
"data": [],
"time": "2020-05-06T08:44:07+00:00"
}, {
"nodeId": "text40",
"nodeType": "DTMF",
"order": 31,
"type": "NodeStart",
"data": [],
"time": "2020-05-06T08:44:07+00:00"
}, {
"nodeId": "text40",
"nodeType": "DTMF",
"order": 32,
"type": "NodeResult",
"data": {
"input": [],
"outcome": "timeout"
},
"time": "2020-05-06T08:44:20+00:00"
}, {
"nodeId": "text43",
"nodeType": "Sound",
"order": 33,
"type": "NodeStart",
"data": [],
"time": "2020-05-06T08:44:20+00:00"
}, {
"nodeId": "text43",
"nodeType": "Sound",
"order": 34,
"type": "NodeResult",
"data": [],
"time": "2020-05-06T08:44:32+00:00"
}, {
"nodeId": "text44",
"nodeType": "Sound",
"order": 35,
"type": "NodeStart",
"data": [],
"time": "2020-05-06T08:44:32+00:00"
}, {
"nodeId": "text44",
"nodeType": "Sound",
"order": 36,
"type": "NodeResult",
"data": [],
"time": "2020-05-06T08:44:36+00:00"
}, {
"nodeId": "text45",
"nodeType": "DTMF",
"order": 37,
"type": "NodeStart",
"data": [],
"time": "2020-05-06T08:44:37+00:00"
}, {
"nodeId": "text45",
"nodeType": "DTMF",
"order": 38,
"type": "NodeResult",
"data": {
"input": [],
"outcome": "timeout"
},
"time": "2020-05-06T08:44:49+00:00"
}, {
"nodeId": "exit",
"nodeType": "Hangup",
"order": 40,
"type": "NodeResult",
"data": [],
"time": "2020-05-06T08:44:49+00:00"
}],
"createdOn": "2020-05-06T08:42:48+00:00",
"updatedOn": "2020-05-06T08:44:49+00:00",
"answeredOn": "2020-05-06T08:42:54+00:00"
}
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 blocks their phone number.
In this case, we cannot provide the attribute reference.
{
"id": "94d21117-2768-498c-a401-1b17e581e441",
"attributes": {
"origin": "annabel",
"customer": "1000",
"script": "1001"
},
"direction": "inbound",
"status": "finished",
"localNumber": "31513703800",
"remoteNumber": "anonymous",
"events":
..........
],
"createdOn": "2021-05-19T12:18:25+00:00",
"updatedOn": "2021-05-19T12:18:41+00:00",
"answeredOn": "2021-05-19T12:18:26+00:00"
}
Re