VERMO cloud - Interfaces

The VERMO cloud interfaces specify the communication between the VERMO web manager and the customer system.

General

  • Api-Version: v2
  • Content-Type: application/json
  • Method: POST
  • Sucess Response:
    • HTTP 201 Created if a resource is successfully created
    • HTTP 202 Accepted if an asynchronous request was successfully received
    • otherwise HTTP 200 OK
  • HTTP HEADER field X-Request-Id is optional, will be returned in response, equals to request.
  • HTTP-Error-Codes: e.g.(401 not auth, 400 bad request)
  • Timestamp format ISO 8601

Authentification

The authentication between the VERMO web manager and the customer system is performed using the respective access parameters.
These parameters are present in every POST body.

{
  "auth": {
    "login": "foo",
    "password": "bar",
    "token": "kl23f00mfo0alsdmmfkapoa"
  }
}

Error object

Send this object as response, if an error occured, instead of a defined response message.

"error": {
 "id": "not_found",
 "message": "The visit_id is not found",
 "l10n": [
    {"lang":"de", "message": "Besuch-ID nicht gefunden"}
  ]
}

PersonObject

The PersonObject describes all metainformation available for a customer or lead.

{
 "firstName":"Max",
 "lastName": "Schulze",
 "email":"Max.Schulze@gmx.de",
 "country":"Detschland",
 "city":"Berlin",
 "zipCode":"11234",
 "street":"Bahnhofstrasse 5",
 "organization":"Muster AG",
 "positionInOrganization":"Vertrieb",
 "customerId":"Kundennummer",
 "phone":"030 234567",
 "mobilePhone":"0171 345678",
 "fax":"030 234568",
 "latitude":52.5072111,
 "longitude":13.1449525,
 "crmId":"1234av23",
 "vcardPage1": "Base64 encoded image data - image format: JPEG Representation",
 "vcardPage2": "Base64 encoded image data - image format: JPEG Representation"
}
  • crmId → unique id from CRM, not available on creation in VERMO App

VisitObject

The VisitObject describes a conversation. It contains all information about a conversation with a customer or lead.

{
 "crmId":"1234w",
 "visitId":"v123",
 "personId" : "1234acz34",
 "timeStamp":"2007-08-31T16:47+00:00",
 "startTime":"2007-08-31T16:47+00:00",
 "endTime":"2007-08-31T16:57+00:00",
 "title":"Besuch ABC",
 "exhibitionId":"expo1",
 "exhibitionName":"Messe ABC",
 "questionSetId":"questionSet2",
 "questionSetName":"Standardmessebogen",
 "drawings":[<DrawingObject>,<DrawingObject>],
 "pictures":[<PictureObject>,<PictureObject>],
 "answerValues":[<AnswerValuesObject>,<AnswerValuesObject>],
 "historyObjects":[<HistoryObject>,<HistoryObject>]
}
  • crmId → unique id from CRM, not available on creation in VERMO App

DrawingObject

The DrawingObject describes a sketch which was generated in the visit. It contains a picture in the JPEG format.

{
 "drawingAsJPEG": "Base64 encoded image data - image format: JPEG Representation"
}

PictureObject

The PictureObject describes a photo which was generated in the visit. It contains a picture in the JPEG format.

{
 "pictureAsJPEG": "Base64 encoded image data - image format: JPEG Representation"
}

HistoryObject

The HistoryObject describes an element of the generated visit report. It contains information about shown content or about the executed search function.

{
 "timeStamp":"2007-08-31T16:47+00:00",
 "event":0,
 "subEvent":0,
 "resType":2,
 "refType":1,
 "resourceURL":"https://web.vermo.cloud/...",
 "resourceTitle":"Firmendokument",
 "imageData":"Base64 encoded image data - image format: JPEG Representation",
 "page":0,
 "total":12,
 "start":0,
 "childHistoryObjects":[<historyObject>,<historyObject>]
}

AnswerValuesObject

The AnswerValuesObject describes the answered questions from the questionnaires. These contain only questions and returned answers.
The metadata for questionsections, questions and answers is provided by the web manager VERMO.

{
  "questionsection": {
    "sectionId": "123",
    "identifier": "myInfoSection",
    "name": "Informationen",
    "question": {
      "questionId": "234",
      "identifier": "myFirstQuestions",
      "name": "Meine Frage 1",
      "answer": {
        "answerId": "11234",
        "identifier": "myFirstAnswer",
        "name": "Meine Freitextantwort",
        "value": "MeinFreitext"
      }
    }
  }
}
  • visitId -> unique id from CRM, not available on creation in VERMO App
  • personId -> owner of visit
  • timestamp -> creation date, ISO 8601 timestamp,
  • event: -> HistoryDetail=0,Search=1,ShowDocument=2,Note=3,WordTapped=4
  • subEvent -> None=0,Opened=1,Spent=2,Closed=3,Added=4,Removed=5
  • resType -> Not defined=0, PDF=1,Image=2,Video=3,Web=4
  • refType -> set if different from resType: Not defined=0, PDF=1,Image=2,Video=3,Web=4
  • resourceURL -> url of resource
  • resourceTitle -> title of media library ressource
  • imageData -> Base64 encoded preview JPEG image data
  • page -> specific page in document (pdf)
  • total -> total time (viewed document page or video sequences) in seconds
  • start -> start time (video sequence) in seconds
  • value -> only set for input fields, for selection or checkbox answers use field „name“ for displaying

Kontakte / Leads

Returns the number of changed contacts since the last update.

getContactCount

URL: <Hostname>/<api-Version>/clients/persons/contact_count

  • Request: 
    {
  "lastUpdate": "2007-08-31T16:47+00:00",
  "vermoUserName" : "Max.Mustermann@company.com"
}
  • Response: 
    {
    "contactCount": 10
}
  • lastUpdate -> required on delta update – ISO 8601 timestamp, ’null‘ -> full update
  • vermoUserName -> logged in user name – VERMO App
  • contactCount -> number of changed contacts, ‚0‘ -> no changed contacts

getLeadCount

URL: <Hostname>/<api-Version>/clients/persons/lead_count

Return the number of the changed leads since the last update.

  • Request: 
    {
    "lastUpdate": "2007-08-31T16:47+00:00",
    "vermoUserName" : "Max.Mustermann@company.com"
}
  • Response: 
    {
    "leadCount": 10
}
  • lastUpdate -> required on delta update – ISO 8601 timestamp, ’null‘ -> full update
  • vermoUserName -> logged in user name – VERMO App
  • leadCount -> number of changed leads, ‚0‘ -> no changed leads

getLeads

URL: <Hostname>/<api-Version>/clients/persons/leads

Return the changed Leads since the last update.

  • Request: 
    {
    "lastUpdate": "2007-08-31T16:47+00:00",
    "vermoUserName" : "Max.Mustermann@company.com"
    "leadOffset" : 0,
    "leadCount" : 10
}
  • Response: 
    {
    "lastUpdate": "2007-08-31T16:47+00:00",
    "leadOffset" : 0
    "leadCount" : 2
    "leads": [
          <PersonObject>,<PersonObject>
      ]
}
  • lastUpdate -> required on delta update – ISO 8601 timestamp, ’null‘ -> full update
  • vermoUserName -> logged in user name – VERMO App
  • leadOffset -> start offset for returning leads, no offset return all leads
  • leadCount -> number of leads for returning, no count return all leads beginning at leadOffset
  • lastUpdate -> ISO 8601 timestamp

getContacts

URL: <Hostname>/<api-Version>/clients/persons/contacts

Return the changed contacts since the last update.

  • Request: 
    {
    "lastUpdate": "2007-08-31T16:47+00:00",
    "vermoUserName" : "Max.Mustermann@company.com"
    "contactOffset" : 0,
    "contactCount" : 10
}
  • Response: 
    {
    "lastUpdate": "2007-08-31T16:47+00:00",
    "contactOffset" : 0
    "contactCount" : 2
    "contacts": [
          <PersonObject>,<PersonObject>
      ]
}
  • lastUpdate -> required on delta update – ISO 8601 timestamp, ’null‘ -> full update
  • vermoUserName -> logged in user name – VERMO App
  • contactOffset -> start offset for returning contacts, no offset return all contacts
  • contactCount -> number of contacts for returning, no count return all contacts beginning at leadOffset
  • lastUpdate -> ISO 8601 timestamp

setLead

URL: <Hostname>/<api-Version>/clients/persons/create_lead

Hands over a new contact from the App.

  • Request: 
    {
    "vermoUserName" : "Max.Mustermann@company.com"
    "lead": <PersonObject>
}
  • Response: 
    {
    "crmID":"1234av23"
}
  • vermoUserName -> logged in user name – VERMO App
  • crmID -> unique id

updateLead (planned – not implemented yet)

Hands over a changed lead from the App.

  • Request: 
    {
    "vermoUserName" : "Max.Mustermann@company.com"
    "lead": <PersonObject>
}
  • Response: 
    {
    "success":true
}
  • vermoUserName -> logged in user name – VERMO App

updateContact (planned – not implemented yet)

Hands over a changed contact from the App.

  • Request: 
    {
    "vermoUserName" : "Max.Mustermann@company.com"
    "contact": {
        "firstName":"Max",
        "lastName": "Schulze",
        "email":"Max.Schulze@gmx.de",
        "country":"Deutschland",
        "city":"Berlin",
        "zipCode":"11234",
        "street":"Bahnhofstrasse 5",
        "organization":"Muster AG",
        "positionInOrganization":"Vertrieb",
        "phone":"030 234567",
        "mobilePhone":"0171 345678",
        "fax":"030 234568",
        "latitude":52.5072111,
        "longitude":13.1449525,
        "crmId":"1234av23"
    }
}
  • Response: 
    {
    "success":true
}
  • vermoUserName -> logged in user name – VERMO App
  • crmId -> unique id

Conversation (visit report)

Returns the visit-identifiers to a contact or lead.

getVisitIds

URL: <Hostname>/<api-Version>/clients/person/visits

  • Request: 
    {
    "vermoUserName" : "Max.Mustermann@company.com"
    "personId" : "1234acz34"
}
  • Response: 
    {
    "visitIds": ["v123","v234"]
}
  • vermoUserName -> logged in user name – VERMO App
  • personId -> lead or contact crmId -> owner of visits

getVisit

URL: <Hostname>/<api-Version>/clients/visits/details

Returns the visit details.

  • Request: 
    {
    "vermoUserName" : "Max.Mustermann@company.com"
    "visitId" : "v123"
}
  • Response: 
    {
    "visit": <visit_object>
}
  • vermoUserName -> logged in user name – VERMO App

setVisit

URL: <Hostname>/<api-Version>/clients/visits/create_visit

Hands over a conversation/visit from the App.

  • Request: 
    {
    "vermoUserName" : "Max.Mustermann@company.com"
    "visit": <visit_object>
}
  • Response: 
    {
    "crmId":"1234av23"
}
  • vermoUserName -> logged in user name – VERMO App