logo
API docs by Redocly

Marigold Signals API (0.0.1)

License: All Rights Reserved

Marigold Signals API Reference

By providing a fully documented API reference, we want to enable everyone to maximize the usage of the Marigold Signals & Moments functionality

Authentication

The Marigold Signals V1 API's are using the basic authentication protocol, i.e. key/secret authentication, using the X-Api-Key Header and Value {key}:{secret}. If you have a Marigold Moments account you are able to create an audience configuration. In this audience configuration a key and secret will be automatically created for you to copy paste. The key is by default disabled. If you want to use that key & secret, press the enable button.

Automatically both SDK (public) & server api key (private) will be created and disabled. You can enable them by using the slider or generated a new one. There is no expiry date on it for now.

Errors

Marigold uses the conventional HTTP response codes to indicate successful or failed API requests.

Codes in the 2xx range indicate success.

Codes in the 4xx range indicate an input related error or validation restrictions.

Codes in the 5xx range indicate an error with Marigold Engage servers.

HTTP Status Codes Description
200 - OK We found the request resource
401 - Unauthorized The access key was incorrect
5xx - Server errors Something went wrong on our end. Please try again

OpenAPI specification

We provide the API specification in the format of OpenApi files which can be found in the openapi/ directory:

Authentication

Authentication

Endpoint generates JWT token based on Basic Authentication header

Authorizations:
basicAuth

Responses

Signal tracking record

Record Event

Signal tracking record

Authorizations:
JwtToken
Request Body schema: application/json
One of
specversion
required
string (Schema Version)
Default: "1.0"

Spec version. Fixed value.

Value: "1.0"
type
required
string (Type)
Default: "event.behavior"

Classification/Category of event

Value: "event.behavior"
dataschema
required
string (Data Schema)
Default: ""

A reference to the definition of the structure of data

id
required
string (Event ID)
Default: ""

Identifier for event. Unique per source. GUID

traceId
string (Trace ID)
Default: ""

Unique ID for tracing request across systems

source
required
string (Source)
Default: ""

Platform identifier.':'

time
required
string (Time)
Default: ""

Date and time an event / activity the event relates to

event
required
string (Event)
Default: "booking_complete"

Type of event: send, click, punch, ... Use underscore notation _

Value: "booking_complete"

class
string (Class)
Default: "signal"

Event class

Value: "signal"
accountId
required
string (Account ID)
Default: ""

Platform specific account id (tenant id)

required
Data (object) or Data (object) (Data)

The data Schema

Any of
accountName
string (Account Name)
Default: ""

Account Name

parentAccountId
string (Parent Account ID)
Default: ""

Platform specific parent account Id

organizationId
string (Organization ID)
Default: ""

Marigold ID organization id

organizationBu
string (Organization BU)
Default: ""

Marigold ID organization business unit

organizationName
string (Organization Name)
Default: ""

Marigold ID organization Name

objectType
required
string (Object Type)
Default: "booking"

The type of object we are tracking on, for example punchcard, campaign, journey, site, etc

Value: "booking"
objectId
required
string (Object ID)
Default: ""

Id of the object of interest. Punchcard type id, campaign id, etc...

objectName
required
string (Object Name)
Default: ""

Name of the object to be used in charts

objectVersion
string (Object Version)
Default: ""

Version/revision for the object

parentObjectId
string (Parent Object ID)
Default: ""

Object Id of the parent object,

parentObjectName
string (Parent Object Name)
Default: ""

Name of the parent object,

platformRef
string (Platform Ref)
Default: ""

Platform reference: :::

eventAttributes
object (Event Attributes)

Flexible mechanism to store custom attributes related to the event

source
string (Source)
Default: ""

Tracking. Source

medium
string (Medium)
Default: ""

Tracking. Medium: cpc, email, sms

channel
string (Channel)
Default: ""

Tracking. Channel name

channelId
string (Channel ID)
Default: ""

Tracking. Channel Identifier, can map to a domain name

ip
string (IP Address)
Default: ""

The IP Address

userAgent
string (User Agent)
Default: ""

Tracking. User agent

deviceType
string (Device Type)
Default: ""

Tracking. Device type derived from user agent

country
string (Country)
Default: ""

Geo. Country

region
string (Region)
Default: ""

Geo. Region

city
string (City)
Default: ""

Geo. City

state
string (State)
Default: ""

Geo. State

postalCode
string (Postal Code)
Default: ""

Geo. Postal Code

latitude
number (Latitude)
Default: 0

Geo. Latitude

longitude
number (Longitude)
Default: 0

Geo. Longitude

audienceId
required
string (Audience ID)
Default: ""

Audience/Segment/Filter

profileId
required
string (Profile ID)
Default: ""

Profile identifier

profileAltId
string (Profile Alt ID)
Default: ""

Alternative Profile Id (email, phone number, appId,...)

profileExternalId
string (Profile External ID)
Default: ""

External Profile Id,AK Id

profileAttributes
object (Profile Attributes)

Flexible mechanism to store custom attributes of the member profile

internalCustom
object (Internal Custom)

Internal custom attributes, if needed

debug
object (Debug)

Debug information, if needed

Responses

Request samples

Content type
application/json
Example
{
  • "specversion": "1.0",
  • "type": "event.behavior",
  • "dataschema": "evt:behavior/v1",
  • "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
  • "traceId": "xxxx-xxxx-xxxx-xxxx-xxxx",
  • "source": "sgx:uscluster1",
  • "time": "2007-04-05T14:32:10.700Z",
  • "event": "booking_complete",
  • "class": "signal",
  • "accountId": "2002",
  • "data": {
    • "accountName": "Marigold_account",
    • "parentAccountId": "2001",
    • "organizationId": "2000",
    • "organizationBu": "2002",
    • "organizationName": "Marigold",
    • "objectType": "booking",
    • "objectId": "1001",
    • "objectName": "New Shop",
    • "objectVersion": "2",
    • "platformRef": "loy:us1-cust100:console:hostnamexyz",
    • "eventAttributes": { },
    • "source": "campaign",
    • "medium": "email",
    • "channel": "Email Message",
    • "channelId": "onlineshop.com",
    • "ip": "127.0.0.1",
    • "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.6 Mobile/15E148 Safari/604.1",
    • "deviceType": "ios",
    • "country": "US",
    • "region": "West",
    • "city": "Sunnyvale",
    • "state": "CA",
    • "postalCode": "94089",
    • "latitude": 40.4424,
    • "longitude": 5.53919,
    • "audienceId": "yyyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyy",
    • "profileId": "100.123123",
    • "profileAltId": "john.doe@example.com",
    • "profileExternalId": "john.doe@example.com",
    • "profileAttributes": { },
    • "internalCustom": { },
    • "debug": { }
    }
}

Endpoint processes array of events

Signal tracking records

Authorizations:
JwtToken
Request Body schema: application/json
Array of Booking Complete Event (object) or Booking Start Event (object) or Ecommerce Cart Abandon Event (object) or Ecommerce Cart Add Event (object) or Ecommerce Cart Empty Event (object) or Ecommerce Cart Remove Event (object) or Ecommerce Purchase Event (object) or Game End Event (object) or Game Start Event (object) or Site Browse in Event (object) or Site Sign in Event (object) or Site Sign out Event (object) or Survey Complete Event (object) or Survey Start Event (object) (SignalEvent)
Array
One of
specversion
required
string (Schema Version)
Default: "1.0"

Spec version. Fixed value.

Value: "1.0"
type
required
string (Type)
Default: "event.behavior"

Classification/Category of event

Value: "event.behavior"
dataschema
required
string (Data Schema)
Default: ""

A reference to the definition of the structure of data

id
required
string (Event ID)
Default: ""

Identifier for event. Unique per source. GUID

traceId
string (Trace ID)
Default: ""

Unique ID for tracing request across systems

source
required
string (Source)
Default: ""

Platform identifier.':'

time
required
string (Time)
Default: ""

Date and time an event / activity the event relates to

event
required
string (Event)
Default: "booking_complete"

Type of event: send, click, punch, ... Use underscore notation _

Value: "booking_complete"

class
string (Class)
Default: "signal"

Event class

Value: "signal"
accountId
required
string (Account ID)
Default: ""

Platform specific account id (tenant id)

required
Data (object) or Data (object) (Data)

The data Schema

Responses

Request samples

Content type
application/json
{
  • "signals": [
    • {
      • "specversion": "1.0",
      • "type": "event.behavior",
      • "dataschema": "evt:behavior/v1",
      • "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
      • "traceId": "xxxx-xxxx-xxxx-xxxx-xxxx",
      • "source": "sgx:uscluster1",
      • "time": "2007-04-05T14:32:10.700Z",
      • "event": "booking_complete",
      • "class": "signal",
      • "accountId": "2002",
      • "data": {
        }
      }
    ]
}