Technische documentatie voor integrators

Sidefish v6 API Documentation

General

The Sidefish API is a RESTFUL JSON HTTP API that serves all server functions for creating, reading, updating and deleting Sidefish Platform data.

Successful calls always return a HTTP status 200.

Errors are returned with corresponding HTTP statuses, like 400, 403, 404 , etc. The response body contains an error description.

The scheme below shows a simplified data model.

To summarize: a user is part of an organisation. A user has one or more portfolios with customers inside. A user also has question lists that are shared across his organisation. An organisation has a customer template defining dynamic fields for customer data. An organisation also hass communication templates for personalized dynamic automatic communications to users and customers. A user can invite a customer to answer a question list by creating a session request, linked to a question list. A question list has a report specification, which is a template to generate a report document after the customer completed his session request. This report spec contains dynamic customer data fields, signature positions, or any other dynamic data that we provide.

Endpoint

The Sidefish API is reachable at:

https://sidefish.app/api/v1/ (PRODUCTION)

https://staging.sidefish.app/api/v1/users (STAGING)

Authentication

A. Bearer token

The Sidefish API supports a bearer token in your HTTP request header.

1. Request a JWT token via the login call.

Endpoint	Method	Request Body	Response Body
/login	POST	{ email: string, password: string }	{ token: string }
/logout	POST	{}

2. Use the resulting token an auth header with a bearer token:

authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ....

B. Cookie

The Sidefish API also supports a cookie in your HTTP request header.

1. Request a JWT token via the login call (same as method A).

2. Use the resulting token a cookie called access_token:

cookie: access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....

C. API KEY

The Sidefish API also supports an API Key in your HTTP request header.

1. Get the API key for your user via the Sidefish Platform under "my account".

2. Use the API key in the request header as:

x-api-key: 123456789

D. OAuth 2.0

The Sidefish API also provides its own OAuth 2.0 server.

For more info about authentication using OAuth, please contact us at info@sidefish.be.

USERS

Description	Endpoint	Method	Request Body	Response Body
Get your own user info.	/users/myuser	GET		An object containting your user info. User: { _id: "12345789", ... }

Models

class User {
  public _id?: string;
  public firstname?: string;
  public lastname?: string;
  public email!: string;
  public password?: string;
  public language?: UserLanguage;
  public groups?: UserGroup[];
  public organisation?: Organisation;
  public useOrganisationEmail?: boolean;
  public resetPasswordToken?: string;
  public resetPasswordExpiration?: Date;
  public apiKey?: string;
  public activeToken?: string;
  public activeTokenExpiration?: Date;
  public otp?: string;
  public isDefault?: Boolean;
  public createdAt?: Date;
  public updatedAt?: Date;
  public isActive?: Boolean;
  public isEnabled?: Boolean;
}

PORTFOLIOS & CUSTOMERS

Your customers are always part of a portfolio.

Description	Endpoint	Method	Request Body	Response Body
Get my portoflios	/portfolios	GET		[ Portfolio: { _id: "12345789", ... }, ]
Get portfolio by _id.	/portfolios/:_id	GET		Portfolio: { _id: "12345789", ... }
Get customers in portfolio by _id.	/portfolios/:_id/customers	GET		[ Customer: { _id: "12345789", ... }, ]
Get a single customer by _id.	/customers/:_id	GET		Customer: { _id: "12345789", ... }
Update a single customer by _id.	/customers/:_id	PUT	Customer: { _id: "12345789", ... }	Customer: { _id: "12345789", ... }
Create a single customer inside a portfolio.	/portfolios/:_id/customers	POST	Customer: { ... }	Customer: { _id: "12345789", ... }

Models

class Portfolio {
  public _id?: string;
  public name?: string;
  public organisation?: Organisation;
  public owner?: User;
  public users?: User[];
  public customers?: Customer[];
  public customerTemplate?: CustomerTemplate;
  public isBdayMailingEnabled?: boolean;
  public isDefault?: Boolean;
  public createdAt?: Date;
  public updatedAt?: Date;
  public isActive?: Boolean;
}

class Customer {
  _id: string;
  portfolio: Portfolio;
  customerTemplate: CustomerTemplate;
  data: [{ [field: CustomerField]: string}]; 
  // CustomerField is any field that was configured 
  // in the customerTemplate in your organisation.
  documents: Document[];
  sessions: [string];
  noBdayMail: boolean;
  notes: string;
  createdAt: Date;
  updatedAt: Date;
  isActive: boolean;
}

QUESTIONLISTS

There are question lists that can be used in sessionrequests.

Description	Endpoint	Method	Request Body	Response Body
Get all your questionlists.	/questionlists	GET		An object containting your user info. [ QuestionList: { _id: "12345789", ... }, ]

Models

class QuestionList {
  public _id?: string;
  public name?: string;
  public slug?: string;
  public description?: string;
  public category?: QuestionListCategory;
  public presentationType?: QuestionListPresentationType;
  public reportSpec?: ReportSpec | string;
  public owningOrganisation?: Organisation;
  public questions?: Question[];
  public customerTemplate?: CustomerTemplate;
  public hoursSaved?: Number;
  public createdAt?: Date;
  public updatedAt?: Date;
  public isActive?: Boolean;
}

class Question {
  public _id?: string;
  public slug?: string;
  public description?: string;
  public questionListId?: QuestionList;
  public customerTemplateFieldName?: string;
  public conditions?: Condition[];
  public images?: Image[];
  public content?: string;
  public contentType?: string;
  public responses?: QuestionResponse[];
  public responseType?: ResponseType;
  public uploadButtonText?: string;
  public isMultipleFileUpload?: Boolean;
  public actions?: ResponseAction[];
  public isDefault?: Boolean;
  public createdAt?: Date;
  public updatedAt?: Date;
  public isActive?: Boolean;
  public isLastQuestion?: Boolean;
  public showImages?: Boolean;
  public showConditions?: Boolean;
  public showScores?: Boolean;
  public showReportValues?: Boolean;
  public showLinkedCustomerValue?: Boolean;
}
+
class QuestionResponse {
  public _id?: string;
  index?: number;
  slug?: string;
  content?: string;
  responseType?: string;
  reportValue?: string;
  scoreModifier?: number;
  actions?: ResponseAction[];
}

class ResponseAction {
  public _id?: string;
  // this performs an api call to this action url when this response is given
  index?: number;
  action?: Action;
  arguments?: ResponseActionArgument[];
}


enum Operator {
  and = "and",
  or = "or",
  not = "not",
  "" = "",
}

enum OrginType {
  customerTemplateField = "customerTemplateField",
  response = "response",
  score = "score",
  extraField = "extraField",
  signatureEnabled = "signatureEnabled",
}

enum QuestionListPresentationType {
  chat = "chat",
  survey = "survey",
  form = "form",
}

class Condition {
  public _id?: string;
  operator?: Operator;
  originType?: OrginType;
  origin?: string;
  target?: string; // ... for this response slug/any/none ..
  value?: string; // ... has this value (if applicable, like on input, but not like on a button choice)
}

class Image {
  public _id?: string;
  fileName: string = "";
  isDefault?: Boolean; // is this the default image if no other conditions are met?
  conditions?: Condition[];
  url?: string; // FRONEND ONLY
}

class ResponseType {
  public _id?: string;
  type?: string;
  userFriendly?: string;
  icon?: string;
}

class ResponseActionArgument {
  public _id?: string;
  argumentType?: string; // ex string, number, questionList, reportSpec
  argumentValue?: string; //the value of the string, number or an string
}

SESSIONREQUESTS

A sessionrequest is a request for a customer to complete a questionlist using the Sidefish chat frontend.

Description	Endpoint	Method	Request Body	Response Body
Create sessionrequests.	/sessionrequests	POST	An object containting your user info. [ SessionRequestCreateObject: { ... }, ]	{ success: true, ids: string[], }

Models

class SessionRequestCreateObject {
    "code": string, // request via /api/v1/sessionrequests/generate-codes/<amount>
    "url": string, // example <mijn-bedrijf>.sidefish.be/nl/#/<vragenlijst-identifier>/<session-code>
    "type": "qlist",
    "customer": string, // _id of the customer
    "questionLists": string[], // _id of the questionlist
    "extraFieldsData"?: [{ // extra data to provide to generate the report as defined in the ReportSpec
        "extraField": string, // ReportSpec.extraFields[]._id
        "value": any,
    }],
    "notificationSms"?: {
        "message"!: string,
    },
    "notificationEmail"?: {
        "from"!: string, // the e-mail address of the user or the organisation sending the notification
        "bcc"?: string,
        "subject"!: string,
        "message"!: string, // html email content
    },
    "notificationReminder"?: {
        "from"!: string, // the e-mail address of the user or the organisation sending the notification
        "bcc"?: string,
        "subject"!: string,
        "message"!: string, // html email content
    },
    "isNotificationScheduled"?: boolean, // use scheduling on moment defined in organisation or send immediately (defaults to false)
    "ccSignedDocuments"?: undefined | string, // extra email address to receive signed documents
    "webhookUrl"?: string, // we send a POST request to: <webhookurl> with JSON { session = <session._id> } in the body. This call is tried 3 times.
}