Metadata

To enhance the API experience and make it easier to track your data held within the DIY Surveys Platform we offer the ability to supply metadata along with any API method (where appropriate). This meta data is then returned in any call backs or along with data provision (for example collecting a message history).

Meta Data takes the form of a JSON array and can contain any number of entries to support your needs. For example:

[
    { "RequestID": "1234567890DEFED" },
    { "OrgID": 1010 },
    { "Instance": "ETRERT"},
    { "Campaign": 1242 },
    { "TimeStamp": "2020-02-04T11:47:33.645773+00:00" }
]

You will see from the example that the data can contain strings, numbers and dates. To supply with your API method you reference the metadata element in the JSON structure. For example, when sending an SMS message:

URL: base/Message/Send
Header:
Authorization: Basic ABCDEFG
Method: POST
Content:
{
  "Source": "12345678901",
  "Destination": "12345678901",
  "Message": "message",
  "Reply": true,
  "When": "2020-02-04T11:47:33.645773+00:00",
  "Window": [{ From: "09:00", To: "16:00", Days: "1,2,3,4,5"}],
  "Callback": "https://yourco.com/api/messagetracker",
  "MetaData": 
    [
        { "RequestID": "1234567890DEFED" },
        { "OrgID": 1010 },
        { "Instance": "ETRERT"},
        { "Campaign": 1242 },
        { "TimeStamp": "2020-02-04T11:47:33.645773+00:00" }
    ]
}

Using Metadata in Message Construction

It is possible to use the meta data in your message construction. For example:

URL: base/Message/Send
Header:
Authorization: Basic ABCDEFG
Method: POST
Content:
{
  "Source": "12345678901",
  "Destination": "12345678901",
  "Message": "Hi {name}, Please could you complete this survey {url}",
  "Reply": true,
  "When": "2020-02-04T11:47:33.645773+00:00",
  "Window": [{ From: "09:00", To: "16:00", Days: "1,2,3,4,5"}],
  "Callback": "https://yourco.com/api/messagetracker",
  "MetaData": 
    [
        { "name": "David" },
        { "url": "https://diysurveys.com" },
        { "Instance": "ETRERT"},
        { "Campaign": 1242 },
        { "TimeStamp": "2020-02-04T11:47:33.645773+00:00" }
    ]
}

In this example the name and url metadata values are used in the message and automatically replaced in the message.

Callbacks

When a callback is triggered along with the standard information the additional metadata data is provided. For example (based on the above example):

URL: https://yourco.com/api/messagetracker
Header:
Authorization: Basic ABCDEFG
Method: POST
Content:
{
  "Source": "12345678901",
  "Destination": "12345678901",
  "Message": "the response",
  "When": "2020-02-04T11:47:33.645773+00:00",
  "MessageID": "MS1312312312323",
  "MetaData": 
    [
        { "RequestID": "1234567890DEFED" },
        { "OrgID": 1010 },
        { "Instance": "ETRERT"},
        { "Campaign": 1242 },
        { "TimeStamp": "2020-02-04T11:47:33.645773+00:00" }
    ]
}

For more information on callbacks please check here.

Key Metadata Values

Whilst most metadata values are not reviewed by the DIY Surveys platform in any specific way there are some values that are used by the platform if present:

Value	Description
Campaign	The Campaign is used in the keyword process to match recipient messages to specific keywords for STOP, HELP and INFO. For more information please click here.
Country	The Country is used as a prefix to the destination value in a message. This can be used when the numbers being sent to do not have a country code prefix, which is required for routing and Windows.

Access Token Metadata Values

It is possible to set up default metadata values whilst creating the access token. The metadata you supply as part of the individual calls is then merged with the default metadata. Great care should be taken that these values do not contradict one another as unexpected results can occur.