API Usage examples

In this article you’ll find some examples on how to use our API. To learn more about how to use the API, take a look at the overview

​The API in its full and below referred methods is to be found on apidocs.symplify.com


So, let’s say we have a web shop. In our web shop we sell food. We have a delicious newsletter where we offer different content based on the recipient’s taste palates.
We use Symplify for all our communication with our customers.

1. Signup process

We want to set up a simple newsletter sign up hosted on our site and want the new recipients to be saved in our database in Symplify. To keep it simple, the customer will only enter their email address.

After created the form on our site we need to setup the connection to Symplify with the API.

​First, it’s a good thing to check if the customer already exists in the database.

Use below REST method to check if the customer already exist in the Symplify database:

GET /{customerid}/lists/{id}/contacts/{originalId}

Option 1:

If the customer doesn’t exist you can use the following method to create the new contact:

POST /{customerid}/contacts

You can connect your list with a journey with a Subscriber joins list starter to trigger a welcome flow for all new contacts. 


Option 2:

You can also combine creating a contact and triggering a specific onboarding journey:

POST /{customerid}/journeys/{id}/commence

The starter will provide the information about how to be reached.

2. Order confirmation

We want to set up an order flow so that our customers get the information they need after placing an order.

First step is to create the actual order confirmation email in Symplify. That's done in Journeys and is triggered with an API request starter: 

POST /{customerid}/journeys/{id}/commence

The starter will provide the information about how to be reached.

The journey flow can then be continued with shipping confirmation and other events. Learn more about how to run a journey flow based on external events.


You will probably want to customize the content in these sendouts based on purchased products and estimated shipping details. This can be done by using handlebars in your content, you can build the structure yourself or you can reach out to your Success Manager at Symplify to get a customized layout.

3. Update recipient data

Of course we want to send relevant content to our recipients and to be able to do so, we want to know their taste palates and areas of interests. In our sendouts we therefor include a link to a profile page. We then use the collected data to create segments in Symplify to target specific topics to specific recipients.

​In this case we’ll host the form ourselves so first we create the profile page on our site and then we create the recipient attributes in Symplify responding to the profile page choices. Our recipients can choose the taste palates sour and/or sweet.


So, in Symplify, the attributes must exist on the account:

sour (id 100)
sweet (id 101)

When a contact makes a change to the profile the following method can be used to update the contact in Symplify:

PUT /{customerid}/lists/{id}/contacts/{originalId}

​To update attributes you can either use the attribute name OR the attribute id and send the data to Symplify under ”properties”:

“properties”: {”sour”:”yes”, ”sweet”:”no”}


”properties”: {”100”:”yes”, ”101”:”no”}


4. Hosting unsubscribe page

We want to manage subscription preferences on the profile page on our end so we create the opt out page and confirmation page on our site.

​We tag the link to the opt out page with an encrypted unique ID string {{message.guid}}{{message.id}}.

Example: http://www.example.com/optoutpage.html?id={{message.guid}}{{message.id}}

​Then we add above link in our Symplify sendouts and when a contact clicks unsubscribe he/she will be redirected to our optout profile page.

​Our landing page/optout page should use the following REST methods to identify the recipient and also update its status (if the recipient chooses to do so after reaching opt out page).

​To get the email address of the recipient (together with other attributes if wanted):

GET /{customerid}/lists/contacts?muid={{message.guid}}{{message.id}}

To change the current subscription status of the recipient:

PUT /{customerid}/lists/{id}/contacts/{originalId}/subscriptionstatus



So, with this setup we have a signup, a profile page (where our customers can choose preferred content or unsubscribe) and we have an order confirmation. A nice package.



​5. If you want to investigate if a recipient appears more than once on one recipient list

When recipient enters landingpage / profile page you can also check if recipients appears more than once with below rest method:

GET /{customerid}/lists/{id}/contacts

6. If you want recipients to be able to re-subscribe to a list they have unsubscribed from

PUT /{customerid}/lists/{id}/contacts/{originalId}/subscriptionstatus

Model schema for subscription status:​

SubscriptionStatusDto {
status (SubscriptionStatus) = [‘SUBSCRIBED’ or ‘UNSUBSCRIBED’]: subcsriptionstatus for email,
mobileStatus (MobileSubscriptionStatus) = [‘SUBSCRIBED’ or ‘UNSUBSCRIBED’]: subcsriptionstatus for mobile
Was this article helpful?
0 out of 0 found this helpful