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 Authorization header:

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

Campaigns

Campaigns represents a specific item for collecting survey information.

A campaign may be created for:

  • Reviewing a product

  • Reviewing a service

  • Answering a single open ended question

Campaign List

Create Campaign
POST/campaigns

Create 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!",
  "type": "general",
  "organisationName": "Samelogic",
  "organisationLogoUrl": "http://yourweb/logo.png",
  "question": "How was your Experience?"
}
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"
    },
    "type": {
      "type": "string",
      "enum": [
        "general",
        "product"
      ],
      "description": "The type of campaign. Can be `general` or `product`"
    },
    "organisationName": {
      "type": "string",
      "description": "Name of the organisation requesting the survey"
    },
    "organisationLogoUrl": {
      "type": "string",
      "description": "Organisation Logo Url. Max Dimensions should be 250px by 250px"
    },
    "question": {
      "type": "string",
      "description": "A question that you would like the user to respond to"
    }
  },
  "required": [
    "title",
    "description",
    "type",
    "organisationName",
    "question"
  ]
}
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"
}

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/:id/invitations

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

Example URI

POST /campaigns/:id/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/:id/invitations

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

Example URI

POST /campaigns/:id/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"
}

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",
    "emoji": "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
emoji The emoji selected by the user enum - Delighted, Happy, Meh, Unsatisfied
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 21 Apr 2017