Public data services using a token (public API)

The purpose of the public Engaging Networks Data Services is to provide anonymised data and non-sensitive information which may be useful in order to provide social proofing for advocacy or fundraising campaigns, and to offer supporting services that can be used for an at a glance overview of certain aspects of ongoing account activity, without needing to access the Engaging Networks dashboard.

For an overview of all of our data services, click here.

Before you launch any code based on the use of these services, please ensure you have thoroughly tested that the calls are returning the data you are expecting.

Getting Started

Before you can make any calls, you will need to obtain the public token for your account. This can be found in the Account settings, under Tokens in the dashboard. You will need to be a sub-account admin to be able to access this.

The public token may be freely shared with developers or agencies over email, as it is not considered confidential information, and will not give access to any personal data held in your database.

Do not confuse public tokens with private tokens, which do require special care when handling and should only ever be shared over a secure medium.

The data returned by these calls is cached in a reporting table. This reporting table is refreshed every 15 minutes, so new actions won’t immediately increase the count.

Base URL

The calls are made by accessing a URL directly. This also allows you to access the URL in a web-browser where you are able to see the output of the calls you are making before you start writing any code to process the results. The base URL for the calls is:

https://us.engagingnetworks.app/ea-dataservice/data.service?service= (U.S. server)

https://ca.engagingnetworks.app/ea-dataservice/data.service?service= (Canada server)

The services are served over HTTPS. Unencrypted HTTP is supported, but not recommended.

Authentication

Authentication is performed with each call by passing the ‘token’ parameter as part of the URL.

Data formats available

You are able to specify which format you would like the data to be delivered in. The service supports XML, JSON as well as CSV. If you do not specify which format you require, the default is XML. If you are building tools that will be designed to be run on a page, the recommended format is JSON, as it is very compact and easily parseable in the JavaScript language.

In order to specify the data format, you can pass the ‘contentType’ parameter. Accepted values are xml, json and csv.

The ‘contentType’ parameter can be applied to all calls.

Overview of calls

Call	Description
ActiveJobs	Returns an overview of the current status of all active jobs running in your account.
EaEmailAOTarget	Returns either a summary of the campaign progress or the date and time of the latest submissions. Can be used for ‘roll-call’ type applications, ‘latest to sign’ etc.
EaEmailAOTargetContact	Retrieves information about the contact(s) reachable by a particular Email to Target campaign.
EaDataCapture	Returns the latest participations for a Data Capture type campaign page.
EaSupporterQuestionResponse	Returns the latest answers to a question identified by id.
NetDonor	Returns a summary of donations received by a particular page, or a donations received from individual supporters (anonymised).
ContactsByParty	Display the number of contacts belonging to each party within a database.
AccountReports	Provides sets of reports about account activity for the given public token.
EaAOContactData	Returns data held about contact(s) in an Engaging Networks provided contact database.
EaAOContactDataByPostcode	Returns data held about a particular contact, identified by postcode, in an Engaging Networks provided contact database.
EaSupporterCount	Return a count of supporter/constituent records in the constituent record database associated with the provided public token.
EaCampaignInfo	Provides basic information about a campaign identified by campaignId.
EaBroadcastInfo	Displays summary information about broadcast(s) in the account.
EaReferenceData	Retrieves a client uploaded ‘Reference Data’ file which can be used to augment the information available for particular contacts.
FundraisingSummary	Return per-currency summary information (number of donations and amount) about a fundraising campaign.
FundraisingSummaryByPage	Return information about the number of single and recurring donations for a specific date range, together with amounts in the reporting currencies USD, GBP, EUR, CAD, AUD only. (NOTE: this call does not return test transactions).
RollCall	Returns a list of the latest supporters to participate in the campaign identified by campaignId.
FundraisingRollCall	Returns the latest supporters to donate to a campaign, together with currency and amount.
SupporterData	Returns output detailing which tagged data fields contain data for a supporter identified by email address.
BroadcastMessageAttribute	Returns output detailing which tagged data fields contain data for a supporter identified by email address.
ProfileCount	Returns the number of matching supporters for a particular profile.
JourneyMessageDetails	Returns the current workflows set up in the account.
EventDetails	Returns event details for upcoming events (start date in the future.)

ActiveJobs

Description: Returns an overview of the current status of all active jobs running in your account.

Parameters:

None required

Sample call: https://ca.engagingnetworks.app/ea-dataservice/data.service?service=ActiveJobs&token=your-token-here

Sample output:

<EaData>
 <EaRow>
   <EaColumn name="JOB ID" type="xs:int">12447</EaColumn>
   <EaColumn name="JOB NAME" type="xs:string">User data export 17/07/2018 07:49 AM</EaColumn>
   <EaColumn name="PERCENT COMPLETE" type="xs:decimal">100</EaColumn>
 </EaRow>
 <EaRow>
   <EaColumn name="JOB ID" type="xs:int">12449</EaColumn>
   <EaColumn name="JOB NAME" type="xs:string">User data export 17/07/2018 07:49 AM</EaColumn>
   <EaColumn name="PERCENT COMPLETE" type="xs:decimal">100</EaColumn>
 </EaRow>
</EaData>

Result Limit / Max Rows returned: N/A

EaEmailAOTarget

Description: Returns either a summary of the campaign progress or the date and time of the latest submissions. Can be used for ‘roll-call’ type applications, ‘latest to sign’ etc.

Parameters

Name	Data Type	Required	Values	Description
campaignId	integer	true		The Email to Target campaign to be used. Multiple IDs can be added separated by a comma
resultType	string	false	summary	Mandatory

Sample call (summary):

https://ca.engagingnetworks.app/ea-dataservice/data.service?service=EaEmailAOTarget&token=your-token-here&campaignId=113760&resultType=summary

Sample output:

<EaData>
 <EaRow>
   <EaColumn name="campaignId" type="xs:int">6748</EaColumn>
   <EaColumn name="campaignName" type="xs:string">Contact MP</EaColumn>
   <EaColumn name="pageHits" type="xs:int">92034</EaColumn>
   <EaColumn name="registrations" type="xs:int">4056</EaColumn>
   <EaColumn name="emailsSent" type="xs:int">3930</EaColumn>
   <EaColumn name="participatingSupporters" type="xs:int">4056</EaColumn>
 </EaRow>
</EaData>

Result Limit / Max Rows returned: N/A

EaEmailAOTargetContact

Description: Retrieves information about the contact(s) reachable by a particular Email to Target campaign.

Parameters

Name	Data Type	Required	Values	Description
campaignId	integer	true		The Email to Target campaign that will be used to identify the contact set.
postcode	string	false		If provided the call will return details about the contact(s) relevant only for this postcode.

Sample call:

https://ca.engagingnetworks.app/ea-dataservice/data.service?service=EaEmailAOTargetContact&token=your-token-here&campaignId=113760&postcode=EC1M5PX

Sample output:

Result Limit / Max Rows returned: N/A

EaDataCapture

Description: Return the latest participations for a Data Capture type campaign page.

Parameters:

Name	Data Type	Required	Values	Description
campaignId	integer	true		The Data Capture campaign to provide data for. Multiple IDs can be added separated by a comma
resultType	string	false	summary	Mandatory

Sample call: https://ca.engagingnetworks.app/ea-dataservice/data.service?service=EaDataCapture&token=your-token-here&campaignId=113757&resultType=summary

Sample output:

Result Limit / Max Rows returned: N/A

EaSupporterQuestionResponse

Description: Returns the latest answers to a question identified by id.

Parameters:

Name	Data Type	Required	Values	Description
questionId	integer	true		The numerical identifier of a question in the account
responseOrder	string	false	ascending, descending	Order the returned results first to last or last to first (by timestamp). Default: descending

Sample call: https://ca.engagingnetworks.app/ea-dataservice/data.service?service=EaSupporterQuestionResponse&token=your-token-here&questionId=22976

Sample output:

Demo: see https://github.com/EngagingNetworks/page-builder-code-blocks/blob/master/display-recent-responses-to-questions.md

Result Limit / Max Rows returned: 1000

NetDonor

Description: Returns a summary of donations received by a particular page, or a donations received from individual supporters (anonymised).

Parameters:

Name	Data Type	Required	Values	Description
campaignId	integer	true		The numerical identifier of the campaign.
resultType	string	false	summary	Mandatory

Sample output:

Result Limit / Max Rows returned: N/A

ContactsByParty

Description: Display the number of contacts belonging to each party within a database.

Parameters:

Name	Data Type	Required	Values	Description
constituencyDatabaseId	integer	true		The ID number of the contact database you would like to look connect with.
resultType	string	false	summary

Sample output:

Result Limit / Max Rows returned: N/A

AccountReports

Description: Provides sets of reports about account activity for the given public token.

Parameters:

Name	Data Type	Required	Values	Description
startDate	date	true	DD/MM/YYYY	The starting date for your report
endDate	date	true	DD/MM/YYYY	The end date for your report
resultType	string	true	newjoins,accounttotals,netdonortransactions, netdonoramounts,broadcaststats	The type of report required

Sample output:

newjoins

accounttotals

netdonortransactions

netdonoramounts

broadcaststats

Result Limit / Max Rows returned:

newjoins: 4
accounttotals: 4
netdonortransactions: 2
netdonoramounts: If a donation page accepts multiple currencies, there will be one row per currency.
broadcaststats: 7

EaAOContactData

Description: Returns data held about contact(s) in an Engaging Networks provided contact database.

Parameters:

Name	Data Type	Required	Values	Description
constituencyDatabaseId	integer	true		The ID number of the contact database you would like to look connect with.
postcode	string	false		Limit results to the contact(s) identified for a single postcode only.

Sample call: https://ca.engagingnetworks.app/ea-dataservice/data.service?service=EaAOContactData&token=your-token-here&constituencyDatabaseId=3

Sample output:

Result Limit / Max Rows returned: N/A

EaAOContactDataByPostcode

Description: Returns data held about a particular contact, identified by postcode, in an Engaging Networks provided contact database.

Parameters:

Name	Data Type	Required	Values	Description
constituencyDatabaseId	integer	true		The numerical identifier of the contact database you would like to look connect with.
postcode	string	true*		Valid postcode for a particular constituency

* If a blank value is passed for postcode, all contacts in the database will be returned.

Sample call: https://ca.engagingnetworks.app/ea-dataservice/data.service?service=EaAOContactDataByPostcode&token=your-token-here&constituencyDatabaseId=3&postcode=EC1M5PX

Sample output:

Result Limit / Max Rows returned: N/A

EaSupporterCount

Description: Return a count of supporter/constituent records in the constituent record database associated with the public token.

Parameters:None required

Sample call: https://ca.engagingnetworks.app/ea-dataservice/data.service?service=EaSupporterCount&token=your-token-here

Sample Output:

Result Limit / Max Rows returned: N/A

EaCampaignInfo

Description: Provides basic information about a campaign identified by campaignId.

Parameters:

Name	Data Type	Required	Values	Description
campaignId	integer	true		The numerical identifier of the campaign. If no id is provided, all campaigns currently in the account will be returned. Includes campaigns with status of deleted and blocked.

Sample output:

Result Limit / Max Rows returned: N/A

EaBroadcastInfo

Description: Displays summary information about broadcast(s) in the account.

Parameters:

Name	Data Type	Required	Values	Description
broadcastId	integer	false		If no broadcastId has been specified, returns a list of broadcasts.
startRow	integer	false
endRow	integer	false

Sample output:

Result Limit / Max Rows returned: 21

EaReferenceData

Description: Retrieves a client uploaded ‘Reference Data’ file which can be used to augment the information available for particular contacts.

Parameters:

Name	Data Type	Required	Values	Description
referenceDataName	string	true		The dashboard name of the uploaded reference data file.

Sample output:

Result Limit / Max Rows returned: N/A

FundraisingSummary

Description: Return per-currency summary information (number of donations and amount) about a fundraising campaign.

Parameters:

Name	Data Type	Required	Values	Description
campaignId	integer	true		The numerical identifier of the campaign.
dataField	string	false		Account Data Structure field to use as filter.
dataFieldValue	string	false		Value to filter on for dataField. Note if dataField is set, a value must be provided as dataFieldValue.

Sample output:

Result Limit / Max Rows returned: N/A

FundraisingSummaryByPage

Description: Return information about the number of single and recurring donations for a specific date range, together with amounts in the reporting currencies USD, GBP, EUR, CAD, AUD only.

Parameters:

Name	Data Type	Required	Values	Description
pageid	integer	true		page-builder identifier of the fundraising page.
startDate	date	true	YYYY-MM-DD
endDate	date	true	YYYY-MM-DD

Sample output:

Result Limit / Max Rows returned: N/A

RollCall

Description: Returns a list of the latest supporters to participate in the campaign identified by campaignId.

Parameters:

Name	Data Type	Required	Values	Description
campaignId	integer	true		The numerical identifier of the campaign.
dataSet	integer	true	1,2	Returns values for either Country (1) or City (2) of the participating supporter.
detailRows	integer	false		Limit the number of returned values to X (max 20).

Sample output:

Result Limit / Max Rows returned: 20

FundraisingRollCall

Description: Returns the latest supporters to donate to a campaign, together with currency and amount.

Parameters:

Name	Data Type	Required	Values	Description
campaignId	integer	true		The numerical identifier of the campaign.
dataSet	integer	true	1,2	Returns values for either Country (1) or City (2) of the participating supporter.
dataField	string	false		Account Data Structure field to use as filter.
dataFieldValue	string	false		Value to filter on for dataField. Note if dataField is set, a value must be provided as dataFieldValue.
detailRows	integer	false		Limit the number of returned values to X (max 20).

Sample output:

Result Limit / Max Rows returned: 20

SupporterData

Description: Returns output detailing which tagged data fields contain data for a supporter identified by email address.

Parameters:

Name	Data Type	Required	Values	Description
email	string	true		The email address of the supporter to look up.

Sample output:

Result Limit / Max Rows returned: N/A

BroadcastMessageAttribute

Description: Return a list of email broadcasts in the account, together with any attributes assigned to them.

Parameters:

Name	Data Type	Required	Values	Description
detailRows	integer	false		Limit the number or rows returned

Sample output:

Result Limit / Max Rows returned: 100

ProfileCount

Description: Returns the number of matching supporters for a particular profile.

Parameters:

Name	Data Type	Required	Values	Description
profileName	string			The dashboard name of the profile to return data for.

Sample output:

Result Limit / Max Rows returned: N/A

JourneyMessageDetails

Parameters:

Name	Data Type	Required	Values	Description
workflowCount	integer	false		Limit the number of workflows to return.

Sample output:

Result Limit / Max Rows returned: N/A

EventDetails

Description: Returns event details for upcoming events (start date in the future.)

Parameters:

Name	Data Type	Required	Values	Description
pageStatus	string	false	New, Live, Closed	Filter on page status
publicOnly	string	false	Y, N	Filter on public/private events
sortOrder	string	false	ASC, DESC
eventTag	string	false		Filter on events with a specific tag(s)

Sample output

Result Limit / Max Rows returned: N/A

Appendix

campaignId

The campaign ID is a unique number associated with the campaign. It is not the same as the Page ID, found in the URL. To find the campaignID of a page:

View the page (as preview or live)
View the source HTML of the page (you can usually right-click and choose View Page Source to do this)
Scroll to the very bottom of the page
You should see a comment in a format like this:
The campaignID is the second number between the colons. The first number is the page ID, and the last number the client ID.

questionId

In order to obtain the correct ID number for a question, it is necessary to use the browser’s Developer Tools ‘Network’ tab. This will allow you to inspect the response from calls that are made to page-builder while editing pages.

To locate the data structure containing the questions, edit a page and open any ‘Form block’ for editing, then select the Questions tab. You should now see a call to:

By viewing the Response for this call, you will be able to see the JSON data structure which contains the questionId. The data structure is an array containing both regular questions and so called ‘opt-in’ questions, however each index also contains the question ‘name’, which should help in identifying the correct question.

constituencyDatabaseId lookup

The Engaging Networks contact databases used by Email to Target campaigns within the software are used by certain calls to extract information about particular contacts. The following table allows you to look up the correct ID number of the database to use with the calls:

Description	constituencyDatabaseId
Australia / English : MP	15
Australia / English : State Parliaments	142
Canada / English : Provincial MLA	8
Canada / English : Toronto City Councillors	64
Canada / English : Federal MP	7
Canada / French : Federal MP	10
Canada / French : Provincial MLA	11
Germany / German : German MEPs	93
UK / English : ICB Chairs	110
UK / English : Councillors – Upper Tier	170
UK / English : County Councillors	49
UK / English : District/Unitary Authority Councillors	17
UK / English : Local Media	6
UK / English : London Borough Councillors	168
UK / English : Mental Health Trusts CEOs	173
UK / English : MEP	4
UK / English : MSP Constituency Only	68
UK / English : MSP Region Only	67
UK / English : MSP/AM/MLA /England MP	1
UK / English : NHS Trusts CEOs	174
UK / English : Police Commissioners	97
UK / English : Westminster MP	3
UK / Special : Council Areas Lookup	52
UK / Special : District Council Ward Lookup	114
UK / Special : UK Region Lookup	101
USA / English : Attorneys General	177
USA / English : Congress – House	26
USA / English : Congress – Senate	39
USA / English : New York Councillors	69
USA / English : State Legislature House	58
USA / English : State Legislature Senate	60
USA / English : US State Governors	119