- Created by Remco Raaijmakers , last modified by Jasper van eck (Unlicensed) on May 29, 2020
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 13 Next »
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.
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 on 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.
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 form 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 Annabel Platform Dataformat 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 his 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 for 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 response 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.
{ "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 e-Mandate search
A basic search on all e-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 a 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, the body looks as follows:
FORMAT id: UUID, identifying the call uniquely attributes: associative array direction: string, ENUM DIRECTION status: string, ENUM STATUS localNumber: string, E164 remoteNumber: string, E164 events: list of associative arrays with the following format 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 createdOn: string, RFC3339 updatedOn: string, RFC3339 answeredOn: string, RFC3339, not set if the call has not been answered ENUMS direction: outbound inbound status: ringing active finished no answer busy rejected invalid number failed nodetype: AddResult CheckCallAttempt CheckCounter CheckGenderBirthday CheckVariable DTMF DTMFString Forward Hangup IsCallOutbound IsRemoteMobile IsRemoteVoiceMail IsTimeInInterval Sound WaitForSilence eventtype: NodeStart NodeUpdate NodeResult
{ "id": "e7813601-21ae-465c-bd97-96367bebd0ca", "attributes": { "origin": "annabel", "customer": "6500", "script": "6512", "job": "eb44f88bd968749a620765a382ef3c75c20a657c37499392d59958c5dd944652-06512" }, "direction": "outbound", "status": "finished", "localNumber": "31513703800", "remoteNumber": "31640754459", "host": "8ed68ab81de6", "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" }
- No labels