🌍 This article is publicly available and can be shared.

Overview

This article is written with a technical audience in mind and provides a step-by-step guide for getting consumer and order data out of SoPost via our API. You can use this guide to create a CRM integration, sending consumer and order data captured in SoPost to your chosen CRM or email marketing tool(s).

The process is simple, and can be achieved using no/low code tools (such as Make.com, Zapier, or Mulesoft Anypoint) or via your own development team.

At a high level the process involves:

Creating and catching an order event webhook
Requesting order data from the SoPost API
Sending that data to your downstream applications
Optional: filtering requests based on things like the order status or whether consumers opted in to future marketing

A simple CRM integration diagram using the SoPost API

In diagram form, the process is very simple, but of course can be expanded to cover more complex use cases. This process catches the webhook, checks if the order is approved, then gets the order data from SoPost. It then checks again if the consumer opted in to future marketing and if they did, sends the record to Salesforce.

Setup Guide

Create a webhook

Creating a webhook is simple, and can be done via the Create a webhook endpoint. your request should look like this:

curl --request POST \
     --url http://localhost:8080/webhooks \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "url": "https://example.com",
  "events": [
    "OrderEvent"
  ],
  "entity_type": "Organisation",
  "entity_id": "f3a10b3a-a02f-4568-b1ca-ea6571620f91"
}
'

Set url to your preferred url to receive events
Set events to OrderEvent as above (we only support one event type currently)
If you want to receive webhooks for all campaigns with your organisation set the entity_type and entity_id to the following:
- entity_type = Organisation
- entity_id = Your organisation UUID (retrievable via this endpoint)
If you want to receive webhooks for a specific campaign:
- entity_type = Campaign
- entity_id = the campaigns UUID (retrievable via this endpoint)

You should receive a 201 response from the API if the webhook has been created successfully.

Receiving and processing the webhook

When orders are created or the order status changes, you will receive webhook notifications to your chosen url which look like this:

{
"event_id": "7c4a8d09ca3762af61e59520943dc26494f8941b",
"event": "APPROVED",
"order_id": "53e477dc-f27e-45ba-958a-d23f9cb85741",
"activity_id": "932c6eba-6fc5-4e41-9ea9-5fd2fe950b25" 
}

Every order starts in Pending and then moves to either Approved or Rejected before moving through our distribution stages. An order will stay in pending for less than 10s whilst we run our intelligent filtering process. You will receive a webhook whenever the status changes.

We provide an event_id so that you can ignore events you've already processed. We also provide an event type (eg pending, approved, rejected) to assist you in building your ideal workflow).

The order_id can be used to retrieve more info about the order (see next step).

Get order data

In most use cases, you'll want to get additional information about the order, who placed it, did they opt-in to future marketing, etc.

To retrieve this information you can call the Retrieve an order endpoint. Simply take the order_id you received in the above webhook, supply it as a path parameter and submit the request:

curl --request GET \
     --url http://localhost:8080/orders/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
     --header 'accept: application/json'

If the order exists (and you have permissions to view it) you will receive a 200 response.

Interpreting order data

Most of the data returned via our API is self-explanatory but there are a few sections that require further explanation. See the example below:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "short_id": "9999ABCDEFG",
  "activity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "address": {
    "line_1": "SoPost Ltd",
    "line_2": "The Core, Bath Lane",
    "town": "Newcastle Upon Type",
    "district": "Tyne & Wear",
    "territory": "GBR",
    "postcode": "NE4 5TF"
  },
  "full_name": "Joe Bloggs",
  "email": "joe.bloggs@example.com",
  "provider": "my-integration",
  "identity": "98700f04-e705-4547-a3ee-d38a8cc9293d",
  "telephone": "+441914980123",
  "line_items": [
    {
      "stock_partition_id": "f3a10b3a-a02f-4568-b1ca-ea6571620f91"
    }
  ],
  "status": "APPROVED",
  "consents": [
    {
      "consent_id": "d2271011-4d8a-47e7-9d4a-5045780fbce9",
      "consent_name": "SoPost Marketing Optin",
      "data_handler": "SoPost",
      "status": "APPROVED"
    }
  ],
  "custom_questions": [
    {
      "question_text": "What is your biggest skincare concern?",
      "question_id": "skincare-concern-101",
      "answer": [
        {
          "answer_text": "Signs of ageing",
          "answer_id": "ageing-423"
        },
        {
          "answer_text": "Sun damage",
          "answer_id": "sun-033"
        }
      ]
    }
  ]
}

There are a few IDs listed in the response:

ID	Explanation
id	The order id (should match the request)
short_id	A user friendly order id
activity_id	The activity id that the order was submitted to (activities belong to campaigns and separate out different marketing activities)
identity	A unique identifier that identifies the person placing this order (only for orders created via the SoPost API). If not supplied, a hash of the email address is used.
stock_partition_id	Identifies which stock partition (and indirectly which product) was ordered by the consumer
consent_id	The id of the marketing consent that the consumer opted in to. Could be multiple.
question_id	This is the internal Id that identifies the custom question
answer_id	This is the internal Id that identifies the custom question's answers

If you are using the data here to add consumers to your marketing list, it is important you pay attention to the consents block. If this is empty, the consumer has not provided their consent for future marketing. If this section is populated then the consumer has provided their consent for future marketing.

⚠️ It's possible to have multiple consents configured, if you're working with a retailer for example, so be sure to check the consent id and data handler to opt the consumer in to the correct marketing lists on your side.

Retrieving custom questions and answers with the order's data

The brand might want to gather some information about their consumers during the order submission to be able to have a more complete profile and tailor future marketing communications to the consumer based on data they’ve provided (eg. what type of skin they have, what kind of scents they prefer etc.)

Some things to point out about the custom questions data available in the Order endpoint:

Only questions and answers submitted during the order flow can be retrieved. This does not include questions and answers submitted during feedback post-trial.
If the question is not mandatory and the consumer did not fill it in, nothing will be returned.
If the question accepts multiple answers, they will all be returned.

Sending the data to a CRM or marketing tool(s)

This step will differ depending on your chosen system and use case, but now that you have access to the order, consumer and opt-in data you can send it downstream to your applications. For example, you can create or update a contact in Salesforce, add a consumer to an email marketing list in Klaviyo, or create a new record in Hubspot - the possibilities are endless.

How to get started

In order to get started you'll need to reach out to integrations@sopost.com to get access to our developer portal and get your API credentials.