Back to top

Welcome to the Samelogic API

The Samelogic API provides you with an integration point to create video based surveys and receive analyzed responses.

Endpoints

Samelogic is a multi-tenant service, which means every customer will have their own instance and api endpoint.

https://your-instance/api/

Authorization

To start using the API, you will need an API Key. You may request this from us.

All HTTP request going through the API must have the API Key in the ApiKey header:

ApiKey: c2afbf53-44b3-4996-a73b-22608dc1f50c

Campaigns

Campaigns are used to aggregate analytics that are computed from submissions. Campaigns are also used to group related surveys that allows users to submit their own video or audio via a weblink or facebook messenger.

Campaigns Collection

Create Campaign
POST/campaigns

Creates a new campaign.

Example URI

POST /campaigns
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "How was your call with us?",
  "description": "You matter to us, we'll make sure to act upon your feedback!",
  "languageCode": "en"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Single line title."
    },
    "description": {
      "type": "string",
      "description": "A short description about the campaign."
    },
    "languageCode": {
      "type": "string",
      "enum": [
        "en",
        "fr",
        "de"
      ],
      "description": "The language code that will be used to analyze the submissions with."
    }
  },
  "required": [
    "title",
    "description",
    "languageCode"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "6349e410-68a1-4d1d-abab-3f3b29db2066"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": 400,
  "reason": "Unknown JSON property"
}

Campaign

Get Campaign
GET/campaigns/{id}

Get the campaign by Id

Example URI

GET /campaigns/37a84fad-058b-4bbb-aeb4-bddc4879f962
URI Parameters
HideShow
id
string (required) Example: 37a84fad-058b-4bbb-aeb4-bddc4879f962
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "How was your call with us?",
  "description": "You matter to us, we'll make sure to act upon your feedback!",
  "languageCode": "en",
  "id": "obXTXJSLtA9K4ybsh",
  "created": "2016-11-11T08:40:51.620Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Single line title."
    },
    "description": {
      "type": "string",
      "description": "A short description about the campaign."
    },
    "languageCode": {
      "type": "string",
      "enum": [
        "en",
        "fr",
        "de"
      ],
      "description": "The language code that will be used to analyze the submissions with."
    },
    "id": {
      "type": "string",
      "description": "Unique identifier."
    },
    "created": {
      "type": "string",
      "description": "Date created."
    }
  },
  "required": [
    "title",
    "description",
    "languageCode",
    "id"
  ]
}
Response  404

Recipients

Recipients represent users who will respond to surveys. By creating a recipient under a campaign, we can personalise the survey for that user.

Recipients

A recipient is a user that can respond to surveys

Create Recipient
POST/recipients

Create a new recipient.

Example URI

POST /recipients
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "email": "test@samelogic.com",
  "phoneNumber": "1-555-555-5555",
  "firstName": "John",
  "lastName": "Doe"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "Email of the recipient"
    },
    "phoneNumber": {
      "type": "string",
      "description": "Phone number of the recipient"
    },
    "firstName": {
      "type": "string",
      "description": "First name of the recipient"
    },
    "lastName": {
      "type": "string",
      "description": "Last name of the recipient"
    }
  }
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "169ef71f-0530-4d98-b78b-e1192d055cd1"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": 400,
  "reason": "Unknown JSON property"
}

Invitations

Invitations are used for inviting recipients to complete a survey. This allows for a personalized survey for each individual user. Invitations can be created for existing recipients by passing in the recipientId in the request body.

Invitations

Create Invitation - new recipient
POST/campaigns/invitations

Create a new invitation. This will also create a new recipient and assign the invitation.

Example URI

POST /campaigns/invitations
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "action": "calling us",
  "actionDate": "2016-11-11T08:40:51.620Z",
  "email": "test@samelogic.com",
  "phoneNumber": "1-555-555-5555",
  "firstName": "John",
  "lastName": "Doe",
  "type": "weblink"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "description": "Used in personlizing the survey. Reminding the user what action they took that prompted the survey."
    },
    "actionDate": {
      "type": "string",
      "description": "Used in personalizing the survey for when the user took the action."
    },
    "email": {
      "type": "string",
      "description": "Email of the recipient"
    },
    "phoneNumber": {
      "type": "string",
      "description": "Phone number of the recipient"
    },
    "firstName": {
      "type": "string",
      "description": "First name of the recipient"
    },
    "lastName": {
      "type": "string",
      "description": "Last name of the recipient"
    },
    "type": {
      "type": "string",
      "enum": [
        "weblink",
        "email"
      ],
      "description": "The type of invitation. `weblink` will return a survey link that you will sent to the user yourself. `email` is not implemented yet."
    }
  },
  "required": [
    "type"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "58d857ae",
  "recipientId": "3cb852fc",
  "surveyLink": "http://your-instance/survey/59b9037d-338a-42cf-93c3-34a0499d51f1?i=e207f85d-78c7-4d07-8727-78d8d9657a71"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "2225-4c4d-9d2c-80322755f986 - Id of the invitation"
    },
    "recipientId": {
      "type": "string",
      "description": "cd33-45c8-8bff-ec35882afc9e - Id of the created recipient"
    },
    "surveyLink": {
      "type": "string",
      "description": "The link to the survey that the user will visit"
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "validation-error",
  "reason": "Type is required",
  "details": [
    {
      "name": "type",
      "type": "required",
      "details": {
        "value": null
      }
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "campaign not found",
  "reason": "No Campaign found with id: ZAo79E46uc9ss9mo"
}

Create Invitation - existing recipient
POST/campaigns/invitations

Create a new invitation. This will assign the invitation to an existing recipient.

Example URI

POST /campaigns/invitations
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "action": "calling us",
  "actionDate": "2016-11-11T08:40:51.620Z",
  "recipientId": "7252b8bd",
  "type": "weblink"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "description": "Used in personlizing the survey. Reminding the user what action they took that prompted the survey."
    },
    "actionDate": {
      "type": "string",
      "description": "Used in personalizing the survey for when the user took the action."
    },
    "recipientId": {
      "type": "string",
      "description": "2d46-4a57-84ec-4711b3b587c8 (required, string) - Id of the recipient"
    },
    "type": {
      "type": "string",
      "enum": [
        "weblink",
        "email"
      ],
      "description": "The type of invitation. `weblink` will return a survey link that you will sent to the user yourself. `email` is not implemented yet."
    }
  },
  "required": [
    "type"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "58d857ae",
  "recipientId": "3cb852fc",
  "surveyLink": "http://your-instance/survey/59b9037d-338a-42cf-93c3-34a0499d51f1?i=e207f85d-78c7-4d07-8727-78d8d9657a71"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "2225-4c4d-9d2c-80322755f986 - Id of the invitation"
    },
    "recipientId": {
      "type": "string",
      "description": "cd33-45c8-8bff-ec35882afc9e - Id of the created recipient"
    },
    "surveyLink": {
      "type": "string",
      "description": "The link to the survey that the user will visit"
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": 400,
  "reason": "Unknown JSON property"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "campaign not found",
  "reason": "No Campaign found with id: ZAo79E46uc9ss9mo"
}

Submissions

Submissions are responses to campaigns that may contain a video or audio to analyze.

Submissions Collection

Create Submission
POST/campaigns/{campaignId}/submissions

Create a new submission

Example URI

POST /campaigns/37a84fad-058b-4bbb-aeb4-bddc4879f962/submissions
URI Parameters
HideShow
campaignId
string (required) Example: 37a84fad-058b-4bbb-aeb4-bddc4879f962
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "surveyId": "8d857ae",
  "invitationId": "8d857ae",
  "mediaUrl": "https://s3-eu-west-1.amazonaws.com/tenant-name/1",
  "experience": "great"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "surveyId": {
      "type": "string",
      "description": "2225-4c4d-9d2c-80322755f986 (optional, string) - Id of the survey used to associated with the submission."
    },
    "invitationId": {
      "type": "string",
      "description": "2225-4c4d-9d2c-80322755f986 (optional, string) - Id of the invitation used to associate with the submission."
    },
    "mediaUrl": {
      "type": "string",
      "description": "The S3 Url link to the video or audio."
    },
    "experience": {
      "type": "string",
      "enum": [
        "great",
        "good",
        "average",
        "bad",
        "awful"
      ],
      "description": "The user's experience."
    }
  }
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "37a84fad-058b-4bbb-aeb4-bddc4879f962",
  "mediaUploadUrl": "http://some.url/to/do/a/PUT/with/binary/objects"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "validation-error",
  "reason": "Type is required",
  "details": [
    {
      "name": "type",
      "type": "required",
      "details": {
        "value": null
      }
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "campaign not found",
  "reason": "No Campaign found with id: 8d857ae-2225-4c4d-9d2c-80322755f986"
}

Submission

Get Submission
GET/submissions/{id}

Get the submission by Id

Example URI

GET /submissions/37a84fad-058b-4bbb-aeb4-bddc4879f962
URI Parameters
HideShow
id
string (required) Example: 37a84fad-058b-4bbb-aeb4-bddc4879f962
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "surveyId": "8d857ae",
  "invitationId": "8d857ae",
  "mediaUrl": "https://s3-eu-west-1.amazonaws.com/tenant-name/1",
  "experience": "great",
  "id": "8d857ae",
  "submittedOn": "2016-11-11T08:40:51.620Z",
  "videoData": {
    "media": {
      "url": "https://s3-eu-west-1.amazonaws.com/tenant-name/1",
      "downloadUrl": "https://s3-eu-west-1.amazonaws.com/tenant-name/1",
      "expires": "2016-11-11T08:40:51.620Z"
    },
    "videoAnalytics": {
      "emotionsExpressed": [
        {
          "emotion": "happy",
          "percent": 0
        }
      ]
    }
  },
  "audioData": {
    "media": {
      "url": "https://s3-eu-west-1.amazonaws.com/tenant-name/1",
      "downloadUrl": "https://s3-eu-west-1.amazonaws.com/tenant-name/1",
      "expires": "2016-11-11T08:40:51.620Z"
    },
    "transcribedTextData": {
      "text": "'some transcribed text'",
      "analytics": {
        "sentimentScore": 0
      }
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "surveyId": {
      "type": "string",
      "description": "2225-4c4d-9d2c-80322755f986 (optional, string) - Id of the survey used to associated with the submission."
    },
    "invitationId": {
      "type": "string",
      "description": "2225-4c4d-9d2c-80322755f986 (optional, string) - Id of the invitation used to associate with the submission."
    },
    "mediaUrl": {
      "type": "string",
      "description": "The S3 Url link to the video or audio."
    },
    "experience": {
      "type": "string",
      "enum": [
        "great",
        "good",
        "average",
        "bad",
        "awful"
      ],
      "description": "The user's experience."
    },
    "id": {
      "type": "string",
      "description": "2225-4c4d-9d2c-80322755f986 (required, string) - Id of the submission"
    },
    "submittedOn": {
      "type": "string",
      "description": "Submitted date in UTC."
    },
    "videoData": {
      "type": "object",
      "properties": {
        "media": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "description": "Authorized Url to view mediaUrl"
            },
            "downloadUrl": {
              "type": "string",
              "description": "Authorized Url that forces a download of the media."
            },
            "expires": {
              "type": "string",
              "description": "When the authorized Urls will expire."
            }
          }
        },
        "videoAnalytics": {
          "type": "object",
          "properties": {
            "emotionsExpressed": {
              "type": "array"
            }
          }
        }
      }
    },
    "audioData": {
      "type": "object",
      "properties": {
        "media": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "description": "Authorized Url to view mediaUrl"
            },
            "downloadUrl": {
              "type": "string",
              "description": "Authorized Url that forces a download of the media."
            },
            "expires": {
              "type": "string",
              "description": "When the authorized Urls will expire."
            }
          }
        },
        "transcribedTextData": {
          "type": "object",
          "properties": {
            "text": {
              "type": "string",
              "description": "The transcribed text."
            },
            "analytics": {
              "type": "object",
              "properties": {
                "sentimentScore": {
                  "type": "number",
                  "description": "Sentiment that represents the transcribed text."
                }
              }
            }
          }
        }
      }
    }
  }
}
Response  404

Webhooks

Webhooks are automatic notifications that are triggered based on certain events.

Submission Processed

Webhook that contains data of the analyzed survey submission.

Event Data

{
    "recipientId": " fca1a509-9c60-4965-9c3a-207a71863bac",
    "invitationId": "3c741b8d-2aba-436c-b36c-80a960ca7b40",
    "campaignId": "ec8d17c2-1c38-44b1-bea2-59f1a1921183",
    "experience": "Happy",
    "emotion": "happiness",
    "emotions": [{
        "percent": 60,
        "emotion": "happiness"
    }, {
        "percent": 50,
        "emotion": "neutral"
    }],
    "videoUrl": "https://samelogic-videos-dev.s3-us-west-2.amazonaws.com/output/ec8d17c2-1c38-44b1-bea2-59f1a1921183.mp4",
    "type ": "video",
    "submitDate ": "2016-10-06 T06:12:12.591Z"
}

Keys

Name Description Type
recipientId The id of the recipient who responded to the survey string
invitationId The id of the invitation representing a specific response string
campaignId The id of the survey related to the campaign responded to string
experience The experience selected by the user enum - great, good, average, bad, awful
emotion The main emotion found in the submission enum - happiness, surprise, contempt, neutral, sadness, disgust, anger, fear
emotions All emotions found in the submission array
type The medium the user used for submitting the survey enum - video, messenger
videoUrl The url to view the video string
submitDate The date the submission was made date

emotions array

Name Description Type
percent The percent of the emotion found in the survey analysis double
emotion The emotion paired with the percent string

Generated by aglio on 12 Oct 2017