Table of Contents

maxLevel	3

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. Image Removed

Image Added

API endpoint

Code Block
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.

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 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.

Section

Column

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.

Column

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.
Use this option for small batches or loose records.

file [FileInput!]

Base64 encoded file.

For example: csv, xml, xlsx, xls, ods.

For large batch import, 1000 or more.
Or when your script requires fields that are not available at the RowInput.

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

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 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

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.

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

language	php

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

language	php

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

language	php

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 e-Mandate search

A basic search on all e-Mandates.

Query

Code Block

language	php

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 a status of a single Mandate.

Query

Code Block

language	php

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

language	php

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

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 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" } } }

Version	Old Version 9	New Version 10
Changes made by	Jasper van eck	Jasper van eck
Saved on	May 29, 2020	May 29, 2020

Page Comparison

Versions Compared

Key

Introduction

GraphQL

API endpoint

Test endpoint

API Keys

Code example

APIs

Import

Required fields

Status codes

Input options

Examples

Row Input

Query

Variables

Response

File Input

Query

Variables

Response

Search batches

Query

Variables

Response

PayLink

Status codes

Examples

Create PayLink

Query

Variables

Response

Simple PayLink search

Query

Variables

Response

Find single PayLink

Query

Variables

Response

Advanced PayLink search

Query

Variables

Response

E-Mandate

Status codes

Examples

Create Mandate

Query

Variables

Response

Simple e-Mandate search

Query

Variables

Response

Find single Mandate

Query

Variables

Response

Advanced Mandate search

Query

Variables

Response

Voice

Examples

Stop calling

Query

Code Blockmutation stopCalling( $scriptId: Int! $reference: String! ){ voice { stopCalling ( scriptId: $scriptId reference: $reference ) } }

Variables

Response

Code Block
mutation stopCalling( $scriptId: Int! $reference: String! ){ voice { stopCalling ( scriptId: $scriptId reference: $reference ) } }