Versions Compared
Version | Old Version 30 | New Version 31 |
---|---|---|
Changes made by | ||
Saved on |
Key
- This line was added.
- This line was removed.
- Formatting was changed.
Table of Contents | ||
---|---|---|
|
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.
View file | ||
---|---|---|
|
API endpoint
Code Block |
---|
https://reminders.alphacommapi.com/v1 |
We use loadbalancers so the IP 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 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.
Code Block |
---|
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
Code Block |
---|
mutation addRecords ( $file: FileInput, $rows: [RowInput!] ) { import { addRecords(file: $file, rows: $rows) { name action status records { scriptId status messages { context message level } } } } } |
Variables
Code Block |
---|
{ "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
Code Block |
---|
{ "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
Code Block |
---|
mutation addFile ( $file: FileInput, $rows: [RowInput!] ) { import { addRecords(file: $file, rows: $rows) { name action status } } } |
Variables
Code Block |
---|
{ "file": { "extension": "csv", "contents": "<<BASE64 ENCODED STRING>>" } } |
Response
Code Block |
---|
{ "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
Code Block |
---|
query ImportSearch( $filters: BatchFiltersInput ) { import { batches( filters: $filters ) { items { name action status } pagination { offset limit total } } } } |
Variables
Code Block |
---|
{ "filters": { "name": { "equalTo": "Test" } } } |
Response
Code Block |
---|
{ "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.
Code Block |
---|
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.
Code Block |
---|
{ "payLink": { "personName": "Alphacomm", "invoiceAmount": "15497", "invoiceCurrency": "EUR", "invoiceDescription": "Example", "invoiceReference": "103482", "invoiceDate": "2019-02-12T10:00:00+00:00" } } |
Response
Code Block |
---|
{ "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
Code Block | ||
---|---|---|
| ||
query { payLink { payLinks { items { status id } } } } |
Variables
No variables needed for this query.
Code Block |
---|
{} |
Response
Code Block |
---|
{ "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
Code Block | ||
---|---|---|
| ||
query PayLinks( $filters: PayLinkFiltersInput ) { payLink { payLinks ( filters: $filters ) { items { id personName personGender status amountPaid createdOn updatedOn } } } } |
Variables
Code Block |
---|
{ "filters": { "id": { "equalTo": "5be41c4f-9fe6-403d-980b-5edc0139ee70" } } } |
Response
Code Block |
---|
{ "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
Code Block | ||
---|---|---|
| ||
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
Code Block |
---|
{ "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
Code Block |
---|
{ "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.
Code Block |
---|
mutation createMandate($mandate: MandateInput!){ mandate { create (mandate: $mandate) { id reference shortUrl longUrl type } } } |
Variables
Example values.
Code Block |
---|
{ "mandate": { "personName": "Alphacomm", "reference": "AC-HUUR" "type": "RCUR", "reason": "huur", "debtorReference": "20190301" } } |
Response
Code Block |
---|
{ "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
Code Block | ||
---|---|---|
| ||
query { mandate { mandates { items { status id } } } } |
Variables
No variables needed for this query.
Code Block |
---|
{} |
Response
Code Block |
---|
{ "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
Code Block | ||
---|---|---|
| ||
query Mandates( $filters: MandateFiltersInput ) { mandate { mandates ( filters: $filters ) { items { id personName status createdOn updatedOn } } } } |
Variables
Code Block |
---|
{ "filters": { "id": { "equalTo": "5be41c4f-9fe6-403d-980b-5edc0139ee70" } } } |
Response
Code Block |
---|
{ "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
Code Block | ||
---|---|---|
| ||
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
Code Block |
---|
{ "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
Code Block |
---|
{ "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
Code Block |
---|
mutation stopCalling( $scriptId: Int! $reference: String! ){ voice { stopCalling ( scriptId: $scriptId reference: $reference ) } } |
Variables
Code Block |
---|
{ "scriptId": 18301, "reference": "your_identifier" } |
Response
Code Block |
---|
{ "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. We are able to 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
Code Block |
---|
... "events": [ { "nodeId": "success", "nodeType": "AddResult", "order": 16, "type": "NodeResult", "data": { "result": "success-ok" }, "time": "2020-05-06T08:43:11+00:00" } ] ... |
Info |
---|
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
Code Block | ||
---|---|---|
| ||
{ "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.
Code Block |
---|
{ "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