Engaging Networks API (ENS)
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
All responses for the service come back as JSON. This header is required on all calls after authentication.
Common Authentication Errors
-
“Invalid api key [XXXXXXXXXXXXXXXXXXXX]” The API key passed into the authenticate request is invalid or the call is being made to the wrong data center. US accounts should use https://us.engagingnetworks.app and International accounts should use https://ca.engagingnetworks.app.
-
“A user was not found for api key[XXXXXXXXXXXXXXXXXXXXX]. Please contact support” The API key passed in does not have a valid user associated to it.
-
“Authentication call is being made from an unregistered source address for this ENS api key” The request is being made from an IP address that is not whitelisted for the ApiUser in EN
-
“The user specified by api key [XXXXXXXXXXXXXXXXXXXX] is not active or does not have access to EN services” The user associated to the API key is inactive or has been removed from the system.
-
“The user with username [api@engagingnetworks.net] has exceeded its api limit” The API user has used up the request limit for the hour and will need to wait before making more requests.
-
“Invalid ens-auth-token” The auth token being used has either expired or is invalid.
These services are used to authenticate to ENS
{token}{token}Pass in your API key to the autenticate call to get back a ens-auth-key to use in alls subsequent calls. NOTE: The ens-auth-key is not required on this call. This call requires the API key to be posted to the system to get back an ens-auth-key.
Request headers
Request body
a022e7be-47ae-4ea9-b435-97e072f639a6
{token}Use this call to validate if your ENS session token is still valid
Path variables
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
{token}Remove this session key for usage.
Path variables
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
These services are for manipulating supporter data
Note:
-
These services are rate limited. If you are ‘syncing’ large amounts of records, please consider using the ‘bulk API’ tools instead. Please contact support for further information.
-
In order to make use of these Supporter API calls, a permission group with the permission ‘Manage individual supporters’ (under Data Management) is enabled and assigned to the API User.
-
Common errors codes
- 10000001: invalid email address
- 10000002: invalid supporter id
- 10000004: updating a supporter’s email address to an existing supporter’s email address
- 10000005: specifying an invalid field on a supporter create/update
- 10000006: unable to retrieve origin source
- 10000007: unable to update origin source
- 10000008: unable to create an origin source
- 10000009: unabel to delete an origin source
- 20000001: invalid question id passed in
{supporterId}{supporterId}{supporterId}{supporterId}/transactions{id}{supporterId}/transactions/recurring{supporterId}/transactions/recurring/{transactionId}{supporterId}/originsource{supporterId}/originsource{supporterId}/originsource{supporterId}/originsource{supporterId}Path variables
Request parameters
Whether to return question responses from the supporter
Whether to return membership details for this supporter
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
Add a new supporter or update an existing supporter if the supporter’s email address already exists in the system.
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
POST https://ca.engagingnetworks.app/ens/service/supporter HTTP/1.1
Content-Type: application/json
{
"Email Address": "joe.smith@noaddress.com",
"questions": {
"Marketing Optin": "N",
}
}Pass in the supporter email address you are looking for (all lowercase)
Request parameters
The email address of the supporter you are looking for (lower case)
If the response should include question responses along with supporter data
Whether to include membership details for this supporter
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
{supporterId}Path variables
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
PUT https://ca.engagingnetworks.app/ens/service/supporter/{supporterId} HTTP/1.1
Content-Type: application/json
{
"Email Address": "joe.smith.updated@noaddress.com"
}{supporterId}Path variables
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
{supporterId}/transactionsGet transactions for this supporter
Path variables
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
Get the list of supporter fields that can be saved or updated for this supporter in the POST/PUT calls.
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
Get the list of question fields that can be saved or updated for this supporter in the POST/PUT calls.
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
Responses
Body
{id}Get a question by id that includes its pull configuration (html field type and field values)
Path variables
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
All responses for the service come back as JSON. This header is required on all calls after authentication.
Query supporters by various search functions.
- latestCreated - the latest supporters created in the system
- latestModified - the latest supporters modified in the system
- suppressed - Supporters that are currently suppressed in the system
- profile - Supporters that belong to a particular profile
Request parameters
the type of query to perform (latestCreated, latestModified, suppressed, profile)
the number of days to go back for the search, this is not required for profile searches but required for all other types. Valid values are 1 to 32.
the export group to use that identifies the attributes of the supporter to return
the ID of the profile to return the supporters for (only applies when type=profile)
the row to start from for pagination
the number of rows to return (maximum=100)
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
Return the supporters that have been suppressed in the past 7 days
/supporter/query?type=suppressed&daysBack=7Return the list of supporters that belong to a particular profile
/supporter/query?type=profile&daysBack=10&profileId=333Get the list of supporters that have been created in the past 3 days using export group ‘basic only’
/supporter/query?type=latestCreated&daysBack=3&exportGroup=basic only{supporterId}/transactions/recurringGet recurring transactions for the given supporter
Path variables
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
{supporterId}/transactions/recurring/{transactionId}Update a recurring transaction. The available attributes to update a recurring transaction are its day of charge (paymentDay), amount, and its status (‘ACTIVE’, ‘PAUSED’, ‘CANCELED’).
{ “amount” : “12.15”, “paymentDay” : 15, “status” : “ACTIVE” }
Path variables
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
{supporterId}/originsourceGet origin source details for a supporter
Path variables
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
Responses
Body
{supporterId}/originsourceAdd an origin source to a supporter
Path variables
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
Request body
{supporterId}/originsourceUpdate a supporter’s origin source
Path variables
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
Request body
{supporterId}/originsourceRemove a supporter’s origin source.
Path variables
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
A set of services that can be used to manipulate pages built in EN.
Note: These services are rate limited. If you are ‘syncing’ large amounts of records, please consider using the ‘bulk API’ tools instead. Please contact support for further information.
{pageId}{pageId}/processGet all pages by type and status. type is a required parameter and status is optional.
Valid values for type are [dcf,mem,ems,unsub,pet,leadgen,survey,ecommerce,premium,sp,ss,sh,cc,tp,ev,ec,et,nd]
Valid values for status are [live,new,tested,close]
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
{pageId}Gets basica attributes about a page
Path variables
Return some basic attributes about a page
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
Responses
Body
["Save the Whales","Trees"]["fr-FR","fr-CA"][“facebook”,“email”]
{pageId}/processProcess an EN page
A few notes regarding processing events through ENS
- The attendee list indicates the number of tickets being bought. So if you pass in one attendee, you are buying one ticket, if you pass in 5, you are buying tickets for that ticket.
- For the attendee element, an email address is required and must be submitted. The other attributes are all optional.
- The transaction element does not require a ‘donationAmt’ attribute. To pass in an additional amount, you will use event.addtionalAmount to do that.
- The example listed below is for a paid event. For free you would pass “cash” as paymenttype
- The rest of the payload should be self explanatory and match how we post data through a page.
Path variables
Processes a page built in EN
Request headers
The ens-auth-token is the session token obtained from authenticating to ENS using your api key and is required on all calls after authentication.
Responses
Body
Process a data capture page this time using standard supporter field properties. For question responses, the componentId of the question is used in the attribute name.
POST https://ca.engagingnetworks.app/ens/service/page/100/process HTTP/1.1
ens-auth-token: f472b605-bae1-4e26-ad5b-829c91735f63
Content-Type: application/json
{
"standardFieldNames": true,
"supporter": {
"firstName": "Joe",
"lastName": "Smith",
"emailAddress": "joe.smith@noaddress.com",
"NOT_TAGGED_1": "a generic field response"
"questions": {
"question.4512": "Y"
}
},
"trackingId": "fb111",
"appealCode": "client appeal code",
"txn1": "client-ext-ref-value1",
"txn2": "client-ext-ref-value2"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 1231231,
"status": "SUCCESS",
"supporterEmailAddress": "joe.smith@noaddress.com",
"supporterId": 2343122
}Process a data capture page
POST https://ca.engagingnetworks.app/ens/service/page/100/process HTTP/1.1
ens-auth-token: f472b605-bae1-4e26-ad5b-829c91735f63
Content-Type: application/json
{
"supporter": {
"First Name": "Joe",
"Last Name": "Smith",
"Email Address": "joe.smith@noaddress.com",
"questions": {
"Marketing Optin": "Y",
"Interested Emails": "daily emails"
}
},
"suppressAutoResponder": true,
"trackingId": "fb111",
"appealCode": "client appeal code",
"txn1": "client-ext-ref-value1",
"txn2": "client-ext-ref-value2"
}Process a donation page
POST https://ca.engagingnetworks.app/ens/service/page/{pageId}/process HTTP/1.1
ens-auth-token: f472b605-bae1-4e26-ad5b-829c91735f63
HTTP/1.1 200 OK
Content-Type: application/json
{
"supporter": {
"Email Address": "joe.smith@noaddress.com",
"First Name": "Joe",
"Last Name": "Smith",
"Address 1": "111 Main St",
"region": "DE",
"Postcode": "23433",
"Country": "USA"
},
"transaction": {
"paymenttype": "VISA",
"donationAmt": "1.00",
"ccnumber": "4222222222222220",
"ccexpire": "12/2018"
},
"trackingId": "fb111",
"appealCode": "client appeal code",
"txn1": "client-ext-ref-value1",
"txn2": "client-ext-ref-value2"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 67710,
"type": "CREDIT_SINGLE",
"currency": "GBP",
"status": "SUCCESS",
"error": "",
"recurringPayment": false,
"paymentType": "VISA",
"amount": 1,
"transactionId": "ND3212T5291521174653468672__A659106__A3E6A98",
"supporterEmailAddress": "joe.smith@noaddress.com",
"supporterId": 139846,
"createdOn": 1487353181180
}
Process an advocacy page
POST https://ca.engagingnetworks.app/ens/service/page/{pageId}/process HTTP/1.1
ens-auth-token: f472b605-bae1-4e26-ad5b-829c91735f63
HTTP/1.1 200 OK
Content-Type: application/json
{
"demo": true,
"supporter": {
"First Name": "Spider",
"Last Name": "Man",
"Email Address": "spider.man@avengers.com",
"Address 1": "100 Main St",
"Postal Code": "43031",
"Country": "US"
},
"contactMessage": {
"subject": "Please help",
"message": "{contact_data~salutation}\nMr Freeze is destroying the city!\n\nKind regards,\n\nSpidey"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 67710,
"status": "SUCCESS",
"supporterEmailAddress": "spider.man@avengers.com",
"supporterId": 139846,
"createdOn": 1487353181180
}donationAmt is an additional amount that can be applied on top of the membership. promoCode is optional.
POST https://ca.engagingnetworks.app/ens/service/page/100/process HTTP/1.1
ens-auth-token: f472b605-bae1-4e26-ad5b-829c91735f63
Content-Type: application/json
{
"supporter": {
"Email Address": "joe.smith@noaddress.com",
"First Name": "Joe",
"Last Name": "Smith",
"Address 1": "111 Main St",
"Region": "DE",
"Postcode": "23433",
"Country": "USA"
},
"transaction": {
"paymenttype": "VISA",
"donationAmt": "5",
"ccnumber": "4222222222222220",
"ccexpire": "12/2020"
},
"membership": {
"promoCode": "",
"membershipVariantId": 157,
"members": [
{
"firstName": "Joe",
"lastName": "Supporter",
"emailAddress": "joe.supporter111@noaddress.com",
"address1": "111 Main St",
"city": "Rockville",
"region": "MD",
"postcode": "12345",
"country": "US",
"phoneNumber": "111-222-3333"
}
]
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 1231231,
"status": "SUCCESS",
"supporterEmailAddress": "joe.smith@noaddress.com",
"supporterId": 2343122
}Process an event page that is configured in Engaging Networks
POST https://ca.engagingnetworks.app/ens/service/page/{pageId}/process HTTP/1.1
ens-auth-token: f472b605-bae1-4e26-ad5b-829c91735f63
Content-Type: application/json
{
"supporter": {
"Email Address": "aleksandar+12345@engagingnetworks.net",
"First Name": "Joe",
"Last Name": "Smith",
"Address 1": "111 Main St",
"region": "DE",
"Postcode": "23433",
"Country": "USA"
},
"transaction": {
"paymenttype": "VISA",
"ccnumber": "4222222222222220",
"ccexpire": "12/2022"
},
"event": {
"discount": "TestDiscount",
"tickets": [
{
"ticketId": 1972,
"quantity": 2,
"attendees": [
{
"title": "Mr",
"firstName": "Foo",
"lastName": "Bar",
"emailAddress": "foo1@bar.com",
"address1": "2 main",
"address2": "Unit 5",
"city": "San Diego",
"region": "CA",
"postCode": "92105",
"country": "US",
"phoneNumber": "999 999 9999",
"dietaryPreference": "Nut allergies",
"mobilityRequirement": "Easy access",
"other1": "Oth1",
"other2": "Oth2",
"other3": "Oth3",
"other4": "Oth4",
"other5": "Oth5",
"other6": "Oth6"
},
{
"title": "Mr",
"firstName": "Pat",
"lastName": "Smith",
"emailAddress": "pat@example.com"
}
]
},
{
"ticketId": 1978,
"quantity": 3,
"attendees": [
{
"title": "Mr",
"firstName": "Foo",
"lastName": "Bar",
"emailAddress": "foo1@bar.com",
"address1": "2 main",
"address2": "Unit 5",
"city": "San Diego",
"region": "CA",
"postCode": "92105",
"country": "US",
"phoneNumber": "999 999 9999",
"dietaryPreference": "Nut allergies",
"mobilityRequirement": "Easy access",
"other1": "Oth1",
"other2": "Oth2",
"other3": "Oth3",
"other4": "Oth4",
"other5": "Oth5",
"other6": "Oth6"
},
{
"title": "Mr",
"firstName": "Pat",
"lastName": "Smith",
"emailAddress": "pat@example.com"
},
{
"title": "Mr",
"firstName": "Matt",
"lastName": "Bourke",
"emailAddress": "matt@example.com"
}
]
}
]
},
"trackingId": "fb111",
"appealCode": "client appeal code",
"txn1": "client-ext-ref-value1",
"txn2": "client-ext-ref-value2"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 23433,
"type": "CREDIT_SINGLE",
"currency": "USD",
"status": "SUCCESS",
"error": "",
"recurringPayment": false,
"paymentType": "VISA",
"amount": 100,
"transactionId": "ND839485948594385943__A234343__AFJ234343",
"supporterEmailAddress": "joe.smith@noaddress.com",
"supporterId": 234333,
"createdOn": 1657353181180
}Run your saved queries as jobs and download the results to a CSV
{en_job_id}{en_job_id}/downloadSubmit an export job to the EN platform
- format should be “Transaction” or “User Data”
- queryName is a stored query for exporting data
- fieldGroup is an export group in your account
POST https://ca.engagingnetworks.app/ens/service/exportjob HTTP/1.1
Content-Type: application/json
{
"displayUserDataInTransactionExport":false,
"applyCustomReferenceNames":false,
"fileType":"csv",
"queryName":"HighGivers",
"format":"Transaction",
"fieldGroup": "UserDataOnly"
}
Response
{
"id": 2343432,
"createdOn": 165892834983483,
"status": "pending"
}Get a list of your running marketing automations and add programtically add more supporters to your automation.
{maId}{maId}/stats{maId}/supporter/bulkGet marketing automations by folderId
GET https://ca.engagingnetworks.app/ens/service/ma?folderId=2434 HTTP/1.1 {maId}/supporter/bulkAdd an array of supporters (up to 1000 per call) to your marketing automation.
NOTE: The supporter must exist in EN, not be supressed or in the exclude criteria of the marketing automation.
Path variables
Add six supporters to an automation with ID 10010
POST https://ca.engagingnetworks.app/ens/service/ma/10010/supporter/bulk HTTP/1.1
Content-Type: application/json
[2374873,980432,89495845,7834792,12637263,908734]