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

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