Engaging Networks Services: REST services

Advanced users only.

Our ENS REST API provides authentification services, supporter management and page services all in one package which means you could create an app or data syncing software.

To start using ENS REST you need to have an API User set up with a whitelisted IP address and the appropriate permissions.

The syntax of ENS can be found here.

What services are available?

Authentication Services

You must first authenticate to ENS. There are calls to do this as well as to validate authentication and to delete the session.

Supporter Services

These calls allow you to get a supporter by ID/email address, add/update/delete a supporter, update a supporter email, get supporter transactions/fields/questions, query supporters, get/update recurring transactions, get/add/update/delete origin source

The API user will need to be in a permission group with the VIEW permission checked for Data Management > Supporter Data > Manage individual supporters to run supporter calls

Page Services

You can use these services to process a page request to an existing page. This is useful if you are developing your own external forms instead of using a page-builder page.

It will create the transaction within Engaging Networks in the same way as when they submit to the page-builder page.

By default, it will send the auto-acknowledgement. It does not pick up the Campaign References in the page’s admin panel, so you need to include these in the call if required.

In addition to process pages, you can get a list of pages by type, or get a page’s details.

Our API accepts and records data as long as the supporter column or question exists in the account – it doesn’t matter if it’s on the page.

Examples

Authenticate then add a new supporter

Create an API User which will provide you with a token
POST to https://ca.engagingnetworks.app/ens/service/authenticate with key of Content-Type and value of application/json; charset=UTF-8 in the Header, and the token in the body
If successful, you will get an ens-auth-token returned with an expiry date
You can then GET supporter details as a JSON object via https://ca.engagingnetworks.app/ens/service/[email protected] with a Header key of ens-auth-token and the returned token as the value. This will return a JSON object containing the supporter fields including supporterID
You can then GET their transactions as a JSON object (with the token in the header again) via https://ca.engagingnetworks.app/ens/service/supporter/XXXXX/transactions where XXXX is the supporterID
You can also POST a new supporter (with the token in the header and also Content-Type of application/json) with the JSON in the body which consists of field names in your supporter record and their values, e.g.
{ "First Name": "Jane", "Last Name": "Smith", "Email": "jane.smith@noaddress.com", "questions":{ "Opt in":"Y" } }

Process an email-to-target page

An example of body code for an email-to-target is below. Note: This always submits as LIVE unless you add demo: true as in the example below.

POST https://ca.engagingnetworks.app/ens/service/page/{PAGEID}/process

Body:

{ "demo": true,
"supporter": { 
"First Name": "Iain",
"Last Name": "Ure",
"Email Address": "iain@example.com",
"Postcode": "e123aa" },
  "questions": { 
    "Opt in": "Y"
    }, 
    "contactMessage": { 
    "subject": "A custom subject", 
    "message": "A message from {user_data~First Name} to {contact_data~firstName}" 
    } 
    }

Process a donation page with external references

In this example, we are posting a recurring donation along with external references:

Creating a new supporter with an Origin Source

‘Origin Source’ can be set through the REST API by passing a value through “originSource”

Example :

Limits

The page processing limits are 200 requests per 5 mins, from a single source (IP address).

The ENS REST limit is 5,000 requests per 1 hour per API User.

Beyond these limits, requests are blocked.