Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
maxLevel3

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. 

Altair add records exampleImage Removed

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.

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

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.

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"
Table of Contents
maxLevel4

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

Image Added


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

API endpoint

Code Block
https://reminders.alphacommapi.com/v1

Our API is behind load balancers so an IP change 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 must 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 and visible in the portal on the import page.

Note

When sending records to our API, we still starting import the records according to your account’s Import schedule. These import windows are visible at your upload page.

Info

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 set up in our portal may be set up 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 set up we will provide a list of required fields. You can also use our matrix of required fields for medium and services.

Status codes

More information about status codes, which are used at the portal and the 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 set up a new script we will inform you about the required fields.

Row Input

This is an example of a mail with PayLink record using the RowInput.

Status
colourGreen
titlePOST
Query body
Code Block
mutation addRecords (
  $file: FileInput,
  $rows: [RowInput!]
) {
  import {
    addRecords(file: $file, rows: $rows) {
      name
      action
      status
      records {
        scriptId
        status
        reference
        messages {
          context
          message
          level
        }
      }
    }
  }
}
Variables
Code Block
{
    "rows": [
      {
        "reference": "f0e7a0c3",
        "script": "1001",
        "personFamilyName": "Alphacomm",
        "toMailAddress": "reminders@alphacomm.nl",
        "toPhoneNumbers" => [
         "+31612345678",
        ],
        "invoiceDescription": "Example payment",
        "invoiceDate": "2019-04-04",
        "invoiceDueDate": "2019-07-30",
        "invoiceReference": "40824524",
        "invoiceCurrency": "EUR",
        "invoiceAmount": "56445",
        "invoiceNumber": "249075245",
        "personBirthDay": "2000-01-01"
      }
    ]
}
Response
Status
title200

We only return the records that were send during the request. This makes it easier to validate if added records are accepted, using the record’s reference.

Code Block
{
  "data": {
    "import": {
      "addRecords": {
        "name": "20190403-965",
        "action": "IMPORT",
        "status": "done",
        "records": [
          {
            "reference": "f0e7a0c3",
            "scriptId": "1001",
            "status": "accepted",
            "messages": []
          }
        ]
      }
    }
  }
}


File Input

This is an example with FileInput. Your file should be sent as a 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 is possible to send a second request to get the status of the batch.

Status
colourGreen
titlePOST
Query body
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
Status
title200

When a file is imported we will always respond with a status queued. Bacause we need some time to process the file.

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.

Status
colourGreen
titlePOST
Query body
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
Status
title200
Code Block
{
  "data": {
    "import": {
      "batches": {
        "items": [
          {
            "name": "Test",
            "action": "VALIDATE",
            "status": "empty"
          }
        ],
        "pagination": {
          "offset": 0,
          "limit": 20,
          "total": 1
        }
      }
    }
  }
}


To use this service we need to configure your iDEAL bank credentials and set up 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.

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.

Status
colourGreen
titlePOST
Query body
Code Block
mutation createPayLink($payLink: PayLinkInput!){
  payLink {
    create (payLink: $payLink) {
      attributes { id value }
      id
      shortUrl
      longUrl
    }
  }
}
Variables

This is the minimal information we need to create a PayLink.

Us the field visibleUntil to set the date when payment should not be possible anymore.

By default, the PayLink expires 90 days after the date of creation.

Code Block
{
   "payLink": {
    "attributes": [
      {"id": "source", "value": "whatsapp"}
    ],
    "personName": "Alphacomm",
    "invoiceAmount": "15497",
    "invoiceCurrency": "EUR",
    "invoiceDescription": "Example",
    "invoiceReference": "103482",
    "invoiceDate": "2019-02-12T10:00:00+00:00"
  }
}
Response
Status
title200
Code Block
{
  "data": {
    "payLink": {
      "create": {
        "attributes": [
          {
            "id": "customer_source",
            "value": "whatsapp"
          },
          {
            "id": "origin",
            "value": "api"
          }
        ],
        "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.

Status
colourGreen
titlePOST
Query body
Code Block
languagephp
query {
  payLink {
    payLinks {
      items {
        status
        id
      }
      pagination {
        offset
        limit
        total
      }
    }
  }
}
Variables

No variables are needed for this query.

Code Block
{}
Response
Status
title200
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"
          }
        ],
        "pagination": {
          "offset": 0,
          "limit": 20,
          "total": 3
        }
      }
    }
  }
}

An example of how to get the status of a single PayLink.

Status
colourGreen
titlePOST
Query body
Code Block
languagephp
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
Status
title200
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"
          }
        ]
      }
    }
  }
}

Simple PayLink search

A basic search on all PayLinks.

Query
}

Search PayLink with record identifer

PayLinks can not only be created through our API but also though the import to our scripts. In this last case the PayLink is delivered by us via email or SMS.

During a record import you are required to define the ‘idenfification_identifier' or also called 'reference’. In case you want to know what the current status of the PayLink is your are able to search our PayLink service with this reference.

Status
colourGreen
titlePOST
Query body
Code Block
languagephp
query {PublicApiPayLinks(
  payLink$filters: {PayLinkFiltersInput
  $order: PayLinkOrderInput
payLinks { $offset: Int
  $limit: Int
items) {
  payLink {
    status
        id
      }
    }payLinks (
  } }
Variables

No variables needed for this query.

Code Block
{}
Response
Code Block
{   "data"filters: {$filters
      "payLink"order: {$order
      "payLinks"offset: $offset
{      limit: $limit
 "items": [  ) {
       { items {
          "status": "paid",attributes {
            "id": "a6e8b63c-927f-476b-8d47-d323e20e1a4f"
          },  value
        {  }
          "status": "cancelled",id
          personName
  "id": "348bd90d-da76-4211-93c3-601cbb15f33a"       personGender
   },       status
   {     }
      }
"status": "ready",   }
}
Variables
Code Block
{
  "filters": {
    "idattributes": "389f0187-6b5d-4896-8d78-e56a6bb1a156"[
      {
   }   	"id": "reference",
    ]  	"equalTo": "20220216-6"
    	}
    }]
  }
}

An example of how to get the status of a single PayLink.

Query
Code Block
languagephp
query PayLinks( $filters: PayLinkFiltersInput ) { payLink
Response
Status
title200
Code Block
{
  "data": {
    "payLink": {
      "payLinks": {
    payLinks (   "items": [
   filters: $filters     ) {
        items {   "attributes": [
      id        {
  personName           personGender   "id": "origin",
      status           amountPaid"value": "sms"
          createdOn    },
      updatedOn        {
}       }     } }
Variables
Code Block
{   "filtersid": { "script",
        "id": {       "equalTovalue": "5be41c4f-9fe6-403d-980b-5edc0139ee70"1003"
      }   } }
Response
Code Block
{   "data": { },
    "payLink":  {       "payLinks": {
        "items": [       "id": "reference",
  {              "idvalue": "5be41c4f-9fe6-403d-980b-5edc0139ee70",20220216-6"
            "personName": "Demo", }
           "personGender": "U" ],
            "statusid": "paid42c949b9-5945-4273-912d-00f5563df1fd",
            "amountPaidpersonName": 0"Alphacomm",
            "createdOnpersonGender": "2019-02-05T09:57:14+00:00M",
            "updatedOnstatus": "2019-02-05T09:57:14+00:00ready"
          }
        ]
      }
    }
  }
}

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

Status
colourGreen
titlePOST
Query body
Code Block
languagephp
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
Status
title200
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.

Status
colourGreen
titlePOST
Query body
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
Status
title200
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 query for all e- Mandates.

Status
colourGreen
titlePOST
Query body
Code Block
languagephp
query {
  mandate {
    mandates {
      items {
        status
        id
      }
    }
  }
}
Variables

No variables are needed for this query.

Code Block
{}
Response
Status
title200
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

Single Mandate

An example of how to get a the status of a single Mandate.

Status
colourGreen
titlePOST
Query body
Code Block
languagephp
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
Status
title200
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 of 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.

Status
colourGreen
titlePOST
Query body
Code Block
languagephp
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
Status
title200
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 requestcommon actions.

Stop

calling

Calling

Use this action to remove any leftover scheduled voice calls, related to the specified scriptId and reference.

Status
colourGreen
titlePOST
Query body
Code Block
mutation stopCalling(
  $scriptId: Int!
  $reference: String!
){
  voice {
    stopCalling (
      scriptId: $scriptId
      reference: $reference
    )
  }
}
Variables
Code Block
{
  "scriptId": 18301,
  "reference": "your_identifier"
}
Response
Status
title200
Code Block
{
  "data": {
    "voice": {
      "stopCalling": "done"
    }
   }
}

Webhook

The voice service supports the use of webHooks, the body looks as follows:

Code Block
languagejson
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
Code Block
languagejson
{
	"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": [],
		}
}

Webhook events

Note

We are working on adding more events and improving the information in the payload. So the content of the data might change.

We can authenticate to your webhook with basic access authentication. At the moment we need to configure your webhook URL.

Voice

Via our webhook you will get information about all the call actions we do for the record given to us. In a regular setup, this means you might get a busy call result in the morning and the afternoon a successful one, because at that moment the phone call was answered.

Call completed

Field

Format

datetime
string

When the event occurred

RFC3339
2023-10-12T07:20:50.52Z

id
string

Identifying the call.

UUID

d670a4af-8562-4d5f-ae30-5cc36acf82ee

serviceId
string

Identifier of the Call Request.

UUID

a2654d8a-3f8d-402e-a03b-980953802a09

service
string

voice
To indicate this is a voice event.

voice

reference
string

Identifier used during import, also known as identification_identifier

20220908-1547471

event
string

Code Block
VoiceCallCompleted

data
array

Contains the details of the call.

See Data table below.

Data

direction
string

Call direction

ENUM DIRECTION

Code Block
  outbound
  inbound

status
string

The call status

ENUM STATUS

Code Block
  ringing
  active
  finished
  no answer
  busy
  rejected
  invalid number
  failed

localNumber
string

The phone number we use when calling

E.164

remoteNumber
string

E.164 or anonymous

events
array

Array of events during the call,
contains the following fields

Code Block
languagejson
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 array when call is not answered.

Code Block
NODETYPE:
  AddResult
  CheckCallAttempt
  CheckCounter
  CheckGenderBirthday
  CheckVariable
  DTMF
  DTMFString
  Forward
  Hangup
  IsCallOutbound
  IsRemoteMobile
  IsRemoteVoiceMail
  IsTimeInInterval
  Sound
  WaitForSilence

EVENTTYPE:
  NodeStart
  NodeUpdate
  NodeResult

answeredOn
string

Empty if the call has not been answered

RFC3339 or empty
2019-10-12T07:20:50.52Z

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:0011+00:00"
	}, {
		"nodeId": "text10",
		"nodeType": "Sound",
		"order": 8,
		"type": "NodeResult",
		"data": [],
		"time": "2020-05-06T08:43:05
      }
    ]
...
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 completed outbound call

Expand
titleCall completed, answered
Code Block
{
  "datetime": "2022-09-08T14:22:52+00:00",
},
 
{
 
"
nodeId
id": "
filter
f3e445ce-75ee-4c94-9d6d-370949664fd7",
  "
nodeType
serviceId": "
CheckGenderBirthday
f3e445ce-75ee-4c94-9d6d-370949664fd7",
"order":
 
9,
 
"
type
service": "
NodeStart
voice",
"data":
 
[],
 
"
time
reference": "
2020-05-06T08:43:05+00:00" }, { "nodeId
20231208-1547471",
  "event": "
filter
VoiceCallCompleted",
  
"
nodeType
data": {
    "
CheckGenderBirthday
direction"
,
: 
"
order": 10, "type
outbound",
    "status": "
NodeResult
finished",
"data": { "gender

    "localNumber": "
M
3225882397",
"age": 2020, "outcome

    "remoteNumber": "
man
316123456789"
}, "time
,
    "answeredOn": "
2020
2022-
05
09-
06T08
08T14:
43
23:
05
10+00:00"
}, {
,
    "events": [
      {
        "nodeId": "
text11m
vm_beep",
        "nodeType": "Sound",

        "order": 
11
1,

        "type": "NodeStart",

        "data": [],

        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
05
13+00:00"

      },
      {

        "nodeId": "
text11m
vm_beep",

        "nodeType": "Sound",

        "order": 
12
2,

        "type": "NodeResult",

        "data": [],

        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
08
16+00:00"

      },
      {

        "nodeId": "
name
vm_wait_for_silence",

        "nodeType": "
Sound
WaitForSilence",

        "order": 
13
3,

        "type": "NodeStart",

        "data": [],
        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
09
17+00:00"
      
},
      {

        "nodeId": "
name
vm_wait_for_silence",

        "nodeType": "
Sound
WaitForSilence",

        "order": 
14,
4,
        "type": "NodeResult",
        "data": [],

        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
10
18+00:00"
      },
      {

        "nodeId": "
success
name",

        "nodeType": "
AddResult
Sound",
"order": 15,

        "order": 5,
        "type": "NodeStart",
        "data": [],

        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
11
18+00:00"
      
},
      {

        "nodeId": "
success
name",

        "nodeType": "
AddResult
Sound",

        "order": 
16,
6,
        "type": "NodeResult",
"data": { "result": "success-ok" },

        "data": [],
        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
11
20+00:00"
      
},
      {

        "nodeId": "
collect
invoice_
id
reference",

        "nodeType": "Sound",

        "order": 
17,
7,
        "type": "NodeStart",

        "data": [],

        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
11
20+00:00"

      },
      {

        "nodeId": "
collect
invoice_
id
reference",

        "nodeType": "Sound",

        "order": 
18,
8,
        "type": "NodeResult",

        "data": [],

        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
16
22+00:00
" }, {
"
      },
      {
        "nodeId": "
text22
vmresult",

        "nodeType": "
Sound
IsRemoteVoiceMail",
        "order": 
19,
9,
        "type": "NodeStart",

        "data": [],

        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
17
22+00:00"
      
},
      {

        "nodeId": "
text22",
vmresult",
        "nodeType": "
Sound
IsRemoteVoiceMail",

        "order": 
20,
10,
        "type": "NodeResult",
        "data":
[], "time": "2020-05-06T08:43:23+00:00" }, { "nodeId
 {
          "detected": "
amount
HUMAN",
"nodeType

          "outcome": "
Sound", "order": 21, "type": "NodeStart", "data": [],
no"
        },
        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
24
22+00:00"
      
},
      {

        "nodeId": "
amount
text2",

        "nodeType": "Sound",

        "order": 
22,
11,
        "type": "
NodeResult
NodeStart",

        "data"
: [],
: [],
        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
28
22+00:00"
      
},
      {

        "nodeId": "
text30
text2",

        "nodeType": "Sound",

        "order": 
23,
12,
        "type": "
NodeStart
NodeResult",

        "data": [],

        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
29
25+
00:00"
00:00"
      },
      {
        "nodeId": "
text30
success",

        "nodeType": "
Sound
AddResult",

        "order": 
24
13,

        "type": "
NodeResult
NodeStart",

        "data": [],

        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
45
25+00:00"
     
}, {
 },
      {
        "nodeId": "
text31
success",

        "nodeType": "
Sound
AddResult",

        "order": 
25,
14,
        "type": "
NodeStart
NodeResult",

        "data":
[],
 {
          "result": "success-ok"
        },
        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
46
25+
00:00"
00:00"
      },
      {
        "nodeId": "
text31
text3",

        "nodeType": "
Sound
DTMF",

        "order": 
26
15,

        "type": "
NodeResult
NodeStart",

        "data": [],

        "time": "
2020
2022-
05
09-
06T08
08T14:
44
23:
07
25+00:
00" }, {
00"
      },
      {
        "nodeId": "
businesshours
text3",
        "nodeType": "
IsTimeInInterval
DTMF",

        "order": 
27,
16,
        "type": "
NodeStart
NodeResult",
"data

        "data": {
          "input": [
], "time

            "3"
          ],
          "outcome": "
2020-05-06T08:44:07+00:00" }, { "nodeId": "businesshours_forward_switch", "nodeType": "CheckVariable", "order": 29, "type": "NodeStart", "data": [],
tone:3"
        },
        "time": "
2020
2022-
05
09-
06T08
08T14:
44
23:
07
31+00:00"
}, {

      },
      {
        "nodeId": "
text40
pre_send_sms",
        "nodeType": "
DTMF
Sound",

        "order": 
31,
17,
        "type": "NodeStart",

        "data": [],
        "time": "
2020
2022-
05
09-
06T08
08T14:
44
23:
07
32+00:00"
      
},
      {
"nodeId": "text40",

        "nodeId": "remote_hangup",
        "nodeType": "
DTMF
RemoteHangup",
        "order": 
32
18,

        "type": "
NodeResult
RemoteHangup",
"data": { "input

        "data": [],
"outcome
        "time": "
timeout" }, "time
2022-09-08T14:23:33+00:00"
      }
    ]
  }
}

Example completed outbound busy call

Expand
Code Block
{
  "datetime": "

2020

2022-

05

09-

06T08

09T10:

44

05:

20

41+00:00",
  "id"

}, { "nodeId

: "adbc180b-a494-477f-958d-9f0b050a09c3",
  "serviceId": "

text43

55b22bce-c0fe-43a0-a0f6-c684579e0452",

  "

nodeType

service": "

Sound

voice",

  "

order

reference": 

33

"20220908-3432",
 

 "

type

event": "

NodeStart

VoiceCallCompleted",

  "data":

[], "time

 {
    "direction": 

"2020-05-06T08:44:20+00:00" }, { "nodeId

"outbound",
    "status": "busy",
    "localNumber": "

text43

3225882397",
  

  "

nodeType

remoteNumber": "

Sound

316123456789",
    

"

order

answeredOn": 

34

"",
  

  "

type": "NodeResult", "data": [], "time": "2020-05-06T08:44:32

events": []
  }
}

Example anonymous inbound call

Example message for an anonymous or not recognized inbound call

Someone may be calling from a phone number we cannot match to a record, or they have blocked their phone number.

In this case, we cannot provide the attribute reference.

Code Block
{
  "datetime": "2022-09-08T14:22:52+00:00"
	},
{ 		"nodeId": "text44",
		"nodeTypeid": "Soundf3e445ce-75ee-4c94-9d6d-370949664fd7",
		"order": 35, 		"typeserviceId": "NodeStartf3e445ce-75ee-4c94-9d6d-370949664fd7",
		"data": [], 		"timeservice": "2020-05-06T08:44:32+00:00"
	}, {
		"nodeIdvoice",
  "reference": "text4420220908-1547471",
 		 "nodeTypeevent": "SoundVoiceCallCompleted",
		  "orderdata": 36,
		"type {
    "direction": "NodeResultinbound",
		"data": [],
		"time
    "status": "2020-05-06T08:44:36+00:00"
	}, {
		"nodeIdfinished",
    "localNumber": "text453225882397",
  		  "nodeTyperemoteNumber": "DTMFanonymous",
    		"orderansweredOn": 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"
}"2022-09-08T14:23:10+00:00",
    "events": 
      ..........
    ]
  }
}

PayLink

Event

Field

Format

datetime
string

When the event occurred

RFC3339
2023-10-12T07:20:50.52Z

id
string

Identifying the event uniquely

UUID

d670a4af-8562-4d5f-ae30-5cc36acf82ee

serviceId
string

Identifier of the PayLink

UUID

a2654d8a-3f8d-402e-a03b-980953802a09

service
string

paylink

paylink

reference
string

Identifier used during import, also known as identification_identifier

Empty when PayLink was created through our API.

event
string

Code Block
PayLinkVisited
PayLinkPaid

data
array

Code Block
{
"payment-method": "ideal",
"transaction-amount": 1344 # Amount in cents
}

Example Paid

Code Block
{
  "datetime": "2022-11-11T11:11:11.11Z",
  "id": "f3e445ce-75ee-4c94-9d6d-370949664fd7",
  "reference": "",
  "serviceId": "adbc180b-a494-477f-958d-9f0b050a09c3",
  "service": "paylink",
  "event": "PayLinkPaid",
  "data": {
    "payment-method": "ideal",
    "transaction-amount": 114
  }
}