Pinpointe has added several new API calls and updated many others in an effort to expand the data resources that can be accessed within a Pinpointe account.
Presented below are descriptions of the main elements addressed in each item. Users can now access updated Pinpointe Support API docs (both XML and JSON format) via our Resources library.
[PINPOINTE-1871] - API: The property “subscriber.updatedate” is now updated when a contact’s list membership changes (added to a list or removed from a list)
[PINPOINTE-1873] - API: All API calls that query subscribers now include an option to return list (aka tag) membership information
[PINPOINTE-1874] - API: JSON-interface timestamps -- all date and timestamps now consistently use (UTC) format and time
[PINPOINTE-713] - API: Added new ‘last_updated’ property for subscribers. This is now updated when any of the subscriber’s attributes change
[PINPOINTE-714] - API: Added a new sort/filter parameter for subscriber list API call
[PINPOINTE-711] - API: added paging for subscriber listings.
[PINPOINTE-710] - API: Added a new parameter to fetch default and custom attributes for a subscriber
[PINPOINTE-1860] - API: Added a new ‘GetUserInfo’ method
Improvements
[PINPOINTE-1596] - API: Test/Update docs show consistent usage (booleans; email vs emailaddress, ..) for RequestType "Lists"
[PINPOINTE-1746] - API: Add option to add/update/import subscriber(s) to return the full details
[PINPOINTE-1747] - API: API calls that fail now return a 400 code. Previously all calls returned a 200 code
[PINPOINTE-1745] - API: If API authentication fails, the API now returns a ‘FAILED’ response status of 401
[PINPOINTE-1831] - API: Added an option to make timestamps include timezone information
[PINPOINTE-712] - API: The getsubscriber() api call can now be called by subscriberID and by email address
[PINPOINTE-1843] - API: Enhance UpdateSubscriber and AddOrUpdateSubscribers to accept either email address OR SubscriberID
[PINPOINTE-1846] - API: All Add/update subscriber methods now update the subscriber’s ‘last update-date’ when any custom field values change
Bug Fixes
[PINPOINTE-1880] - API: forms-GetForms FAILS -- returned only the xml start line. This now returns the correct list of forms
DETAIL REVIEW
New Features
Note: The primary contact container in the GUI-based Pinpointe application is called a “database”. When using the API, databases are referred to as “lists”.
In the GUI, you can parse contacts within a given database into “lists”. In the API, lists are referred to as “tags”
[PINPOINTE-1871] - API: The property “subscriber.updatedate” is now updated when a contact’s list membership changes (added to a list or removed from a list)
When a user updates a contact’s tag membership via an API call, the subscriber’s <updatedate> property will now be updated for the transaction. This will allow users to add additional filter rules when doing searches for a specific population of contacts.
[PINPOINTE-1873] - API: All API calls that query subscribers now include an option to return list (aka tag) membership information
Presented below in Fig 1 is a list of API calls that now include the optional <include_membership> tag (XML syntax example).
Fig 1
Fig 2 below shows the API response when the <include_membership> tag’s value is set to “true” (“true”, “1”, “yes” are all acceptable values). As illustrated, the system returns as part of the data the <tags> top-level element, and inside of this are the <tag> element and the tag IDs of any tags this particular contact is in.
Fig 2
[PINPOINTE-1874] - API: JSON-interface timestamps -- all date and timestamps now consistently use (UTC) format and time
All date and timestamps returned by an API call will now be returned in the UTC format, also commonly known as the UNIX Timestamp format. This value can then be programmatically converted to various date/time formats which can also be adjusted for a given time zone during reformatting.
[PINPOINTE-713] - API: Added new ‘last_updated’ property for subscribers. This is now updated when any of the subscriber’s attributes change
This added property will hold the returned date/time value that results when an API call successfully updates any subscriber attribute accessible by the API. This would include changes to status, custom fields, etc. This “when-updated” value can then be used as part of search filter criteria on a population of contacts.
[PINPOINTE-714] - API: Added a new sort/filter parameter for subscriber list API call
Certain API calls that are used to return lists of subscribers now have a <sort> tag which allows the user to sort how the contacts will be returned, such as by status type, date the subscriber was added to the database or by the subscriber ID. The sorted data may be set to ascending or descending sort values. Fig 1 below shows an example of the tag in use.
Calls which contain the <sort> tag:
GetSubscribers
GetNewSubscribers
GetSubscribersById
GetMasterUnsubscribes
Fig 1
[PINPOINTE-711] - API: added paging for subscriber listings
Certain API calls that are used to return lists of subscribers now have a <pagination> tag which allows the user to decide how many subscriber records will be returned per “page”, in addition to setting the starting record (for example, “0” would be to start at the first record, and so on).. Fig 1 below shows an example of the tag.
Calls which contain the <pagination> tag:
GetSubscribers
GetNewSubscribers
GetMasterUnsubscribes
Fig 1
[PINPOINTE-710] - API: Added a new parameter to fetch default and custom attributes for a subscriber
Certain API calls that are used to return populations of subscribers now support retrieving default and custom fields for each subscriber returned. A user may specifically set which fields to return (the example below shows two tags but the user may enter as many as they wish), or the user may just use a single tag and specify “all” as the value (also shown below). Fig 1 below shows an example of the element.
A third option is to use one tag but specify a list of fields to return using an array structure. See Fig 2 below.
Calls which contain this block of tags:
GetSubscribers
GetNewSubscribers
GetSubscribersById
Fig 1
Fig 2
Improvements
[PINPOINTE-1596] - API: Test/Update docs show consistent usage (booleans; email vs emailaddress, ..) for RequestType "Lists"
All API calls have been modified to present a consistent syntax to the user. An example of inconsistent syntax in the past would be where one call would use a tag name of <email> and another would use a tag name of <emailaddress>. All documentation will also be updated to reflect a consistent use of tag names and acceptable tag values.
[PINPOINTE-1746] - API: Add option to add/update/import subscriber(s) to return the full details
Certain API calls now have an added tag, <return_tag>, that accepts a Boolean value (“1”, “yes” or “true” for true; “0”, “no” or “false” for false) that allows the user to specify whether or not the system should return an expanded set of data. This <return_tag> should always be set to a true/yes value if the user is using another connectivity app to connect other third-party applications to their Pinpointe account. Fig 1 below shows an example of the tag.
Calls which contain <return_data> tag:
AddOrUpdateSubscribers
AddSubscriberToList
AddSubscribersToList
UpdateSubscriber
Fig 1
[PINPOINTE-1747] - API: API calls that fail now return a 400 code. Previously all calls returned a 200 code
The application now returns a more well-defined set of failure codes thus improving the ability to diagnose problems and call failures.
[PINPOINTE-1745] - API: If API authentication fails, the API now returns a ‘FAILED’ response status of 401
As with item #1747 above, the application now returns a more well-defined set of failure codes thus improving the ability to diagnose problems and call failures.
[PINPOINTE-1831] - API: Added an option to make timestamps include timezone information
Returned timestamps now include timezone data.
[PINPOINTE-712] - API: The getsubscriber() api call can now be called by subscriberID and by email address
Users now have access to two different methods by which to call and return a population of contacts:
GetSubscribers - retrieves contacts by using the subscriber’s email address property value.
GetSubscribersById - retrieves contacts by using the subscriber’s subscriber ID property value.
[PINPOINTE-1843] - API: Enhance UpdateSubscriber and AddOrUpdateSubscribers to accept either email address OR SubscriberID
In conjunction with item #712 above, a user may now retrieve a contact’s data set by using either the contact’s email address or subscriber ID as the identifier.
[PINPOINTE-1846] - API: All Add/update subscriber methods now update the subscriber’s ‘last update-date’ when any custom field values change
This returned date / time value of the most recent contact update enhances the data set returned by certain calls.
Bug Fixes
[PINPOINTE-1880] - API: forms-GetForms FAILS -- returned only the xml start line. This now returns the correct list of forms
Dale Boyd
Pinpointe - Release 46-B - (April 2021) - API Content Overview
Pinpointe has added several new API calls and updated many others in an effort to expand the data resources that can be accessed within a Pinpointe account.
Presented below are descriptions of the main elements addressed in each item. Users can now access updated Pinpointe Support API docs (both XML and JSON format) via our Resources library.
Here is the link to the XML-based documentation:
https://help.pinpointe.com/support/solutions/folders/5000263496
Here is the link to the JSON-based documentation:
https://help.pinpointe.com/support/solutions/folders/12000016995
New Features
[PINPOINTE-1871] - API: The property “subscriber.updatedate” is now updated when a contact’s list membership changes (added to a list or removed from a list)
[PINPOINTE-1873] - API: All API calls that query subscribers now include an option to return list (aka tag) membership information
[PINPOINTE-1874] - API: JSON-interface timestamps -- all date and timestamps now consistently use (UTC) format and time
[PINPOINTE-713] - API: Added new ‘last_updated’ property for subscribers. This is now updated when any of the subscriber’s attributes change
[PINPOINTE-714] - API: Added a new sort/filter parameter for subscriber list API call
[PINPOINTE-711] - API: added paging for subscriber listings.
[PINPOINTE-710] - API: Added a new parameter to fetch default and custom attributes for a subscriber
[PINPOINTE-1860] - API: Added a new ‘GetUserInfo’ method
Improvements
[PINPOINTE-1596] - API: Test/Update docs show consistent usage (booleans; email vs emailaddress, ..) for RequestType "Lists"
[PINPOINTE-1746] - API: Add option to add/update/import subscriber(s) to return the full details
[PINPOINTE-1747] - API: API calls that fail now return a 400 code. Previously all calls returned a 200 code
[PINPOINTE-1745] - API: If API authentication fails, the API now returns a ‘FAILED’ response status of 401
[PINPOINTE-1831] - API: Added an option to make timestamps include timezone information
[PINPOINTE-712] - API: The getsubscriber() api call can now be called by subscriberID and by email address
[PINPOINTE-1843] - API: Enhance UpdateSubscriber and AddOrUpdateSubscribers to accept either email address OR SubscriberID
[PINPOINTE-1846] - API: All Add/update subscriber methods now update the subscriber’s ‘last update-date’ when any custom field values change
Bug Fixes
[PINPOINTE-1880] - API: forms-GetForms FAILS -- returned only the xml start line. This now returns the correct list of forms
DETAIL REVIEW
New Features
Note: The primary contact container in the GUI-based Pinpointe application is called a “database”. When using the API, databases are referred to as “lists”.
In the GUI, you can parse contacts within a given database into “lists”. In the API, lists are referred to as “tags”
[PINPOINTE-1871] - API: The property “subscriber.updatedate” is now updated when a contact’s list membership changes (added to a list or removed from a list)
When a user updates a contact’s tag membership via an API call, the subscriber’s <updatedate> property will now be updated for the transaction. This will allow users to add additional filter rules when doing searches for a specific population of contacts.
[PINPOINTE-1873] - API: All API calls that query subscribers now include an option to return list (aka tag) membership information
Presented below in Fig 1 is a list of API calls that now include the optional <include_membership> tag (XML syntax example).
Fig 1
Fig 2 below shows the API response when the <include_membership> tag’s value is set to “true” (“true”, “1”, “yes” are all acceptable values). As illustrated, the system returns as part of the data the <tags> top-level element, and inside of this are the <tag> element and the tag IDs of any tags this particular contact is in.
Fig 2
[PINPOINTE-1874] - API: JSON-interface timestamps -- all date and timestamps now consistently use (UTC) format and time
All date and timestamps returned by an API call will now be returned in the UTC format, also commonly known as the UNIX Timestamp format. This value can then be programmatically converted to various date/time formats which can also be adjusted for a given time zone during reformatting.
[PINPOINTE-713] - API: Added new ‘last_updated’ property for subscribers. This is now updated when any of the subscriber’s attributes change
This added property will hold the returned date/time value that results when an API call successfully updates any subscriber attribute accessible by the API. This would include changes to status, custom fields, etc. This “when-updated” value can then be used as part of search filter criteria on a population of contacts.
[PINPOINTE-714] - API: Added a new sort/filter parameter for subscriber list API call
Certain API calls that are used to return lists of subscribers now have a <sort> tag which allows the user to sort how the contacts will be returned, such as by status type, date the subscriber was added to the database or by the subscriber ID. The sorted data may be set to ascending or descending sort values. Fig 1 below shows an example of the tag in use.
Calls which contain the <sort> tag:
GetSubscribers
GetNewSubscribers
GetSubscribersById
GetMasterUnsubscribes
Fig 1
[PINPOINTE-711] - API: added paging for subscriber listings
Certain API calls that are used to return lists of subscribers now have a <pagination> tag which allows the user to decide how many subscriber records will be returned per “page”, in addition to setting the starting record (for example, “0” would be to start at the first record, and so on).. Fig 1 below shows an example of the tag.
Calls which contain the <pagination> tag:
GetSubscribers
GetNewSubscribers
GetMasterUnsubscribes
Fig 1
[PINPOINTE-710] - API: Added a new parameter to fetch default and custom attributes for a subscriber
Certain API calls that are used to return populations of subscribers now support retrieving default and custom fields for each subscriber returned. A user may specifically set which fields to return (the example below shows two tags but the user may enter as many as they wish), or the user may just use a single tag and specify “all” as the value (also shown below). Fig 1 below shows an example of the element.
A third option is to use one tag but specify a list of fields to return using an array structure. See Fig 2 below.
Calls which contain this block of tags:
GetSubscribers
GetNewSubscribers
GetSubscribersById
Fig 1
Fig 2
Improvements
[PINPOINTE-1596] - API: Test/Update docs show consistent usage (booleans; email vs emailaddress, ..) for RequestType "Lists"
All API calls have been modified to present a consistent syntax to the user. An example of inconsistent syntax in the past would be where one call would use a tag name of <email> and another would use a tag name of <emailaddress>. All documentation will also be updated to reflect a consistent use of tag names and acceptable tag values.
[PINPOINTE-1746] - API: Add option to add/update/import subscriber(s) to return the full details
Certain API calls now have an added tag, <return_tag>, that accepts a Boolean value (“1”, “yes” or “true” for true; “0”, “no” or “false” for false) that allows the user to specify whether or not the system should return an expanded set of data. This <return_tag> should always be set to a true/yes value if the user is using another connectivity app to connect other third-party applications to their Pinpointe account. Fig 1 below shows an example of the tag.
Calls which contain <return_data> tag:
AddOrUpdateSubscribers
AddSubscriberToList
AddSubscribersToList
UpdateSubscriber
Fig 1
[PINPOINTE-1747] - API: API calls that fail now return a 400 code. Previously all calls returned a 200 code
The application now returns a more well-defined set of failure codes thus improving the ability to diagnose problems and call failures.
[PINPOINTE-1745] - API: If API authentication fails, the API now returns a ‘FAILED’ response status of 401
As with item #1747 above, the application now returns a more well-defined set of failure codes thus improving the ability to diagnose problems and call failures.
[PINPOINTE-1831] - API: Added an option to make timestamps include timezone information
Returned timestamps now include timezone data.
[PINPOINTE-712] - API: The getsubscriber() api call can now be called by subscriberID and by email address
Users now have access to two different methods by which to call and return a population of contacts:
GetSubscribers - retrieves contacts by using the subscriber’s email address property value.
GetSubscribersById - retrieves contacts by using the subscriber’s subscriber ID property value.
[PINPOINTE-1843] - API: Enhance UpdateSubscriber and AddOrUpdateSubscribers to accept either email address OR SubscriberID
In conjunction with item #712 above, a user may now retrieve a contact’s data set by using either the contact’s email address or subscriber ID as the identifier.
[PINPOINTE-1846] - API: All Add/update subscriber methods now update the subscriber’s ‘last update-date’ when any custom field values change
This returned date / time value of the most recent contact update enhances the data set returned by certain calls.
Bug Fixes
[PINPOINTE-1880] - API: forms-GetForms FAILS -- returned only the xml start line. This now returns the correct list of forms
This issue has been fixed.